/ Hex Artifact Content
Login

Artifact 171a61d64618d49f70eeacc85234c874f7857945:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
39c0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
39d0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
39e0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
39f0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3a00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3a10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3a30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3a40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3a50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3a60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3a70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3a80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3a90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3aa0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3ab0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ac0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3ad0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3ae0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3af0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3b00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3b10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3b20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3b30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3b40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3b50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3b60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3b70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3b80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ba0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3bb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3bc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3bd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3be0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3bf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3c00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3c10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3c20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3c30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3c40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3c50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3c60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3c70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3c80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3c90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3ca0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3cb0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3cc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3cd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3ce0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3cf0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3d00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3d10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3d20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3d30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3d40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3d50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3d60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3d70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3d80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3d90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3da0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3db0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3dc0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3dd0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3de0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3df0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3e00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3e10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3e20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3e30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3e40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3e50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3e60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3e70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3e80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3e90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3ea0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3eb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3ec0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ed0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3ee0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ef0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
3f00: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3f10: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3f20: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
3f30: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
3f40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
3f50: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3f60: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
3f70: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
3f80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3f90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3fa0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3fb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3fc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3fd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3fe0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ff0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4000: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4010: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4020: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4030: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4040: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4050: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4060: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4070: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4080: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4090: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
40a0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
40d0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
40e0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
40f0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4120: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4130: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4140: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4150: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4160: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4170: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41a0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
41b0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
41c0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
41f0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4200: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4210: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4220: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4230: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4240: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4250: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4260: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4270: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
4280: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
4290: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
42a0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
42b0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
42c0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
42d0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
42e0: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
42f0: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4300: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4310: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4320: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4330: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4340: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4350: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4360: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4370: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
4380: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
4390: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43a0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
43b0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
43c0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
43d0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
43e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
43f0: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4400: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4410: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4420: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4430: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4440: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4450: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4460: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4470: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
4480: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
4490: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44a0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
44b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
44c0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
44d0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
44e0: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
44f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4500: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4510: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4520: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4530: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4540: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4550: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4560: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4570: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4580: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
4590: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45a0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
45b0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
45c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
45d0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
45e0: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
45f0: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4600: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4610: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4620: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4630: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4640: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4650: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4660: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4670: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
4680: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
4690: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
46c0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
46d0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
46e0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
46f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4700: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4710: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4720: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4730: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4760: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4770: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
4780: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
4790: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47a0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
47b0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
47c0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
47d0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
47e0: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
47f0: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4800: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4810: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4820: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4830: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4840: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4850: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4860: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4870: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
4880: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
4890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48a0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
48b0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
48c0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
48d0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
48e0: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
48f0: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4900: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4920: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4930: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4940: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4960: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4970: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4980: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4990: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49a0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
49b0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
49c0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
49d0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
49e0: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
49f0: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a00: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a10: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a30: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a40: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4a50: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4a60: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4a80: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4a90: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4aa0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4ab0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4ad0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4ae0: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4af0: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4b10: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4b20: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4b30: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4b40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b50: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4b60: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4b70: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4b80: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4ba0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4bb0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4bc0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4bd0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4be0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4bf0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4c00: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4c10: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4c20: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4c30: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4c40: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4c50: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4c60: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4c70: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4c80: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4c90: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4ca0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4cb0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4cc0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4cd0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4ce0: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4cf0: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4d00: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4d10: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4d20: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4d30: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4d40: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4d50: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4d60: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4d70: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4d80: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4d90: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4da0: 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65  n 3.3.8 and late
4db0: 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75  r) include.** su
4dc0: 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69  pport for additi
4dd0: 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65  onal result code
4de0: 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d  s that provide m
4df0: 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66  ore detailed inf
4e00: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75  ormation.** abou
4e10: 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20  t errors. These 
4e20: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
4e30: 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62   codes] are enab
4e40: 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
4e50: 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61  ** on a per data
4e60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4e70: 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a  basis using the.
4e80: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
4e90: 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
4ea0: 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74  s()] API.  Or, t
4eb0: 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65  he extended code
4ec0: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74   for.** the most
4ed0: 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61   recent error ca
4ee0: 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73  n be obtained us
4ef0: 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
4f00: 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
4f10: 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ()]..*/.#define 
4f20: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4f30: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4f40: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4f50: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4f60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4f70: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4f80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4f90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4fa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4fb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4fc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4fd0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4fe0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4ff0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5000: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
5010: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5020: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
5030: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
5040: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
5050: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5060: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
5070: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5080: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
5090: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50a0: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
50b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50c0: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
50d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50e0: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
50f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5100: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
5110: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5120: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
5130: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5140: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
5150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5160: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
5170: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5180: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
5190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51a0: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
51b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51c0: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
51d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51e0: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
51f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5200: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
5210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5220: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
5230: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5240: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
5250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5260: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
5270: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
5280: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
5290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52a0: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
52b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
52c0: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
52e0: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
52f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5300: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
5310: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5320: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
5330: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5340: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
5350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5360: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
5370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5380: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5390: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53a0: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
53b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
53c0: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
53d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
53e0: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
53f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5400: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5410: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5420: 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20  ERR_SHMMAP      
5430: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5440: 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23  ERR | (21<<8)).#
5450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5460: 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20  ERR_SEEK        
5470: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5480: 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23  ERR | (22<<8)).#
5490: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54a0: 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54  ERR_DELETE_NOENT
54b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
54c0: 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23  ERR | (23<<8)).#
54d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
54e0: 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20  ERR_MMAP        
54f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5500: 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23  ERR | (24<<8)).#
5510: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5520: 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20  ERR_GETTEMPPATH 
5530: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5540: 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23  ERR | (25<<8)).#
5550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5560: 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  ERR_CONVPATH    
5570: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5580: 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23  ERR | (26<<8)).#
5590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55a0: 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20  ERR_VNODE       
55b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
55c0: 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23  ERR | (27<<8)).#
55d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
55e0: 45 52 52 5f 41 55 54 48 20 20 20 20 20 20 20 20  ERR_AUTH        
55f0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5600: 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23  ERR | (28<<8)).#
5610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5620: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
5630: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
5640: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
5650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
5660: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
5670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
5680: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56a0: 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20  BUSY_SNAPSHOT   
56b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56c0: 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29  BUSY   |  (2<<8)
56d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56e0: 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50  _CANTOPEN_NOTEMP
56f0: 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  DIR      (SQLITE
5700: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c  _CANTOPEN | (1<<
5710: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5720: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49  TE_CANTOPEN_ISDI
5730: 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  R          (SQLI
5740: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32  TE_CANTOPEN | (2
5750: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5760: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55  LITE_CANTOPEN_FU
5770: 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53 51  LLPATH       (SQ
5780: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5790: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
57a0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
57b0: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 28  CONVPATH       (
57c0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
57d0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
57e0: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
57f0: 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20 20  _VTAB           
5800: 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   (SQLITE_CORRUPT
5810: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5820: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5830: 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  LY_RECOVERY     
5840: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5850: 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  LY | (1<<8)).#de
5860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5870: 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20  ONLY_CANTLOCK   
5880: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5890: 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23  ONLY | (2<<8)).#
58a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
58b0: 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20  ADONLY_ROLLBACK 
58c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
58d0: 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29  ADONLY | (3<<8))
58e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
58f0: 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44  READONLY_DBMOVED
5900: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5910: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38  READONLY | (4<<8
5920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5930: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
5940: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5950: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
5960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5970: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43  _CONSTRAINT_CHEC
5980: 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  K        (SQLITE
5990: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31  _CONSTRAINT | (1
59a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
59c0: 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51  COMMITHOOK   (SQ
59d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
59e0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5a00: 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20  INT_FOREIGNKEY  
5a10: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5a20: 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  INT | (3<<8)).#d
5a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5a40: 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e  STRAINT_FUNCTION
5a50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5a60: 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29  STRAINT | (4<<8)
5a70: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a80: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e  _CONSTRAINT_NOTN
5a90: 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  ULL      (SQLITE
5aa0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35  _CONSTRAINT | (5
5ab0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5ac0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5ad0: 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51  PRIMARYKEY   (SQ
5ae0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5af0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
5b00: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5b10: 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20 20  INT_TRIGGER     
5b20: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5b30: 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  INT | (7<<8)).#d
5b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5b50: 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20  STRAINT_UNIQUE  
5b60: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b70: 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29  STRAINT | (8<<8)
5b80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b90: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42  _CONSTRAINT_VTAB
5ba0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5bb0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39  _CONSTRAINT | (9
5bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5bd0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5be0: 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53 51  ROWID        (SQ
5bf0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5c00: 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e  |(10<<8)).#defin
5c10: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c20: 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20  RECOVER_WAL     
5c30: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c40: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5c50: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f  e SQLITE_NOTICE_
5c60: 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b  RECOVER_ROLLBACK
5c70: 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20   (SQLITE_NOTICE 
5c80: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
5c90: 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47  e SQLITE_WARNING
5ca0: 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20  _AUTOINDEX      
5cb0: 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47   (SQLITE_WARNING
5cc0: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5cd0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55  ne SQLITE_AUTH_U
5ce0: 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20 20  SER             
5cf0: 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c    (SQLITE_AUTH |
5d00: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5d10: 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f   SQLITE_OK_LOAD_
5d20: 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20  PERMANENTLY     
5d30: 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c  (SQLITE_OK | (1<
5d40: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5d50: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5d60: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5d70: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5d80: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5d90: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5da0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5db0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5dc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5dd0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5de0: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5df0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5e00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5e10: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e30: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5e40: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5e50: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e60: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e80: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5e90: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5ea0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5eb0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ed0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5ee0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5ef0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5f00: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f20: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5f30: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5f40: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f60: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5f70: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5f80: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fa0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5fb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5fc0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fe0: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5ff0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
6000: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6010: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6020: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6030: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
6040: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
6050: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6060: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6070: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6080: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
6090: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
60a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60c0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
60d0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
60e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
60f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6100: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
6110: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
6120: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6130: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6140: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
6150: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
6160: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6180: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
6190: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
61a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61c0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
61d0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
61e0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6200: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6210: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6220: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6240: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6250: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6260: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6270: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6280: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6290: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
62a0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
62b0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
62c0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
62d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
62e0: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
62f0: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6300: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6310: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6320: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6330: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6340: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6350: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6360: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6370: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6380: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
6390: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
63a0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
63b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
63c0: 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43 54 49  PEN_FILEPROTECTI
63d0: 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20 20 20  ON_MASK         
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63f0: 20 20 20 20 20 20 20 20 30 78 30 30 37 30 30 30          0x007000
6400: 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  00../* Reserved:
6410: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6420: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
6430: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6440: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6450: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6460: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6470: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6480: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6490: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
64a0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
64b0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
64c0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
64d0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
64e0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
64f0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
6500: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
6510: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
6520: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6530: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6540: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6550: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6560: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6570: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6580: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6590: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
65a0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
65b0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
65c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
65d0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
65e0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
65f0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6600: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
6610: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
6620: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6630: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6640: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6650: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6660: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6670: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6680: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6690: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
66a0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
66b0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
66c0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
66d0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
66e0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
66f0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6700: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
6710: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
6720: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6730: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6740: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6750: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6760: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6770: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6780: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6790: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
67a0: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
67b0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
67c0: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
67d0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
67e0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
67f0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6800: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
6810: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
6820: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6830: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6840: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6850: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6860: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6870: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6880: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6890: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
68a0: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
68b0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
68c0: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
68d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
68e0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
68f0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
6900: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
6910: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6920: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6930: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6940: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6950: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6960: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6970: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6980: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6990: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
69a0: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
69b0: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
69c0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
69d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69e0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
69f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6a00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a10: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6a20: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a30: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6a40: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a50: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6a60: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a80: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6a90: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6aa0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6ab0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6ac0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6ad0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6ae0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6af0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6b00: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6b10: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b20: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b40: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6b50: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6b60: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6b70: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b90: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6ba0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6bb0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6bc0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6bd0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6be0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c00: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6c10: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6c20: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6c30: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6c40: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6c50: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6c60: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c70: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6c80: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6c90: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6ca0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6cb0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6cc0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6cd0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6ce0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6cf0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6d00: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6d10: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6d20: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6d30: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6d40: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6d50: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6d60: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6d70: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6d80: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6d90: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6da0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6db0: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6dc0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6dd0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6df0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6e00: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6e10: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6e20: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6e30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6e40: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6e50: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6e60: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6e70: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6e80: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6e90: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6ea0: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6eb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6ec0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ed0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6ee0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6ef0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6f00: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6f10: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6f20: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6f30: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6f40: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6f50: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6f60: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6f70: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6f80: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6f90: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6fa0: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6fb0: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6fc0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6fd0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6fe0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6ff0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
7000: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
7010: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7020: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7030: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7040: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7050: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7060: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7070: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7080: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7090: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
70a0: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
70b0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
70c0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
70d0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
70e0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
70f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7100: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
7110: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7120: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7130: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7140: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7150: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7160: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7170: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7180: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7190: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
71a0: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
71b0: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
71c0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
71d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
71e0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
71f0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
7200: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
7210: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7220: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7230: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7240: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7250: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7260: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7270: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7280: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7290: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
72a0: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
72b0: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
72c0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
72d0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
72e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
72f0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
7300: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
7310: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7320: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7330: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7340: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7350: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7370: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7380: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7390: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
73a0: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
73b0: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
73c0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
73d0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
73e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
73f0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
7400: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
7410: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7420: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7430: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7440: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7450: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7460: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7470: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7480: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7490: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
74a0: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
74b0: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
74c0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
74d0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
74e0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
74f0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
7500: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
7510: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7520: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7530: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7540: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7550: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7560: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7570: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7580: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7590: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
75a0: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
75b0: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
75c0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
75d0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
75e0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
75f0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
7600: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
7610: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7620: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7630: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7640: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7650: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7660: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7670: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7680: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7690: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
76a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
76b0: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
76c0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
76d0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
76e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
76f0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
7700: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
7710: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7720: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7730: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7740: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7750: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7760: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7770: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7780: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7790: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
77a0: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
77b0: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
77c0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
77d0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
77e0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
77f0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
7800: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
7810: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7820: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7830: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7840: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7850: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7860: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7870: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7880: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7890: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
78a0: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
78b0: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
78c0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
78d0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
78e0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
78f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7900: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
7910: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7920: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7930: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7940: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7950: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7960: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7970: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7980: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7990: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
79a0: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
79b0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
79c0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
79d0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
79e0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
79f0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7a00: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7a10: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7a20: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7a30: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7a40: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7a50: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7a60: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7a70: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7a80: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7a90: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7aa0: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7ab0: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7ac0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ad0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7ae0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7af0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7b00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7b10: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7b20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7b30: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7b40: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7b50: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7b60: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7b70: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7b80: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7b90: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7ba0: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7bb0: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7bc0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7bd0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7be0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7bf0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7c00: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7c10: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7c20: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7c30: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7c40: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7c50: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7c60: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7c70: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7c80: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7c90: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7ca0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7cb0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7cc0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7cd0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7ce0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7cf0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7d00: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7d10: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7d20: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7d30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7d40: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7d50: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7d60: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7d70: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7d80: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7d90: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7da0: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7db0: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7dc0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7dd0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7de0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7df0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7e00: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7e10: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7e20: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7e30: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7e40: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7e50: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7e60: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7e70: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7e80: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7e90: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7ea0: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7eb0: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7ec0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ed0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7ee0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7ef0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7f00: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7f10: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7f20: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7f30: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7f40: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7f50: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7f60: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7f70: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7f80: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7f90: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7fa0: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7fb0: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7fc0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7fd0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7fe0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7ff0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
8000: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
8010: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8020: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
8030: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8040: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8050: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8060: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8070: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8080: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8090: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
80a0: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
80b0: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
80c0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
80d0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
80e0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
80f0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
8100: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
8110: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8120: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
8130: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8140: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8150: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8160: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8170: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8180: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8190: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
81a0: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
81b0: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
81c0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
81d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
81e0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
81f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8200: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
8210: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8220: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8230: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8240: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8250: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8260: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8270: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8280: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8290: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
82a0: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
82d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
82e0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
82f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
8300: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
8310: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8320: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8330: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8350: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8360: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8370: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8380: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8390: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
83a0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
83b0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
83c0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
83d0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
83e0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
83f0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
8400: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
8410: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
8420: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8430: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8450: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8460: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8470: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8480: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8490: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
84a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
84b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
84c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
84d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
84e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
84f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
8500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8510: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
8520: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8530: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8540: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8550: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8560: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8570: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8580: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8590: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
85a0: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
85b0: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
85c0: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
85d0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
85e0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
85f0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
8600: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
8610: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
8620: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8630: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8640: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8650: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8660: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8670: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8680: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8690: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
86a0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
86b0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
86c0: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
86d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
86e0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
86f0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
8700: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8710: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
8720: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8730: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8740: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8750: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8760: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8770: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8780: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8790: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
87a0: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
87b0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
87c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
87d0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
87e0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
87f0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
8800: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
8810: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
8820: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8830: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8840: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8850: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8860: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8870: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8880: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8890: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
88a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
88b0: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
88c0: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
88d0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
88e0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
88f0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
8900: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
8910: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
8920: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8930: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8940: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8950: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8960: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8970: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8980: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8990: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
89a0: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
89b0: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
89c0: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
89d0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
89e0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
89f0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
8a00: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
8a10: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
8a20: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8a30: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8a40: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8a50: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8a60: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8a70: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8a80: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8a90: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8aa0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ab0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8ac0: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
8ad0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
8ae0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
8af0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8b00: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
8b10: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
8b20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8b30: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8b40: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8b50: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8b60: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8b70: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8b80: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8b90: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8ba0: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
8bc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8bd0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
8be0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
8bf0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
8c00: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
8c10: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
8c20: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8c30: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8c40: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8c50: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8c60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8c70: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8c80: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8c90: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
8ca0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
8cb0: 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  TATE]].** The [S
8cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8cd0: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8ce0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8cf0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8d00: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8d10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8d20: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8d30: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8d40: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8d50: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8d60: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8d70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8d80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8d90: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8da0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8db0: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8dc0: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8dd0: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8de0: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8df0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8e00: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8e10: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8e20: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8e30: 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
8e40: 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51 4c 49  le when the SQLI
8e50: 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d 70 69  TE_TEST.** compi
8e60: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
8e70: 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  s used..**.** <l
8e80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8e90: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8ea0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8eb0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
8ec0: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
8ed0: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
8ee0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
8ef0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
8f00: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
8f10: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
8f20: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
8f30: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
8f40: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
8f50: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8f60: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8f70: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8f80: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8f90: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8fa0: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8fb0: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
8fc0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
8fd0: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
8fe0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
8ff0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
9000: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
9010: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
9020: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
9030: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
9040: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
9050: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
9060: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
9070: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
9080: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
9090: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
90a0: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
90b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
90c0: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
90d0: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
90e0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
90f0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
9100: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
9110: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
9120: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
9130: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
9140: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
9150: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
9160: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
9170: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
9180: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9190: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
91a0: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
91b0: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
91c0: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
91d0: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
91e0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
91f0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9200: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9210: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9220: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9230: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
9240: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9250: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9260: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
9270: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
9280: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9290: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
92a0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
92b0: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
92c0: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
92d0: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
92e0: 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53  on.  See also [S
92f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
9300: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a  NAL_POINTER]..**
9310: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9320: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
9330: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
9340: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f  [SQLITE_FCNTL_JO
9350: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 20 6f  URNAL_POINTER] o
9360: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9370: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
9380: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
9390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
93a0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
93b0: 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 66 69  h the journal fi
93c0: 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a 20 74 68  le (either.** th
93d0: 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72  e [rollback jour
93e0: 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b 77 72 69  nal] or the [wri
93f0: 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d 29 20 66  te-ahead log]) f
9400: 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
9410: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9420: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
9430: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
9440: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 2e 0a 2a  FILE_POINTER]..*
9450: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9460: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9470: 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e  TTED]].** No lon
9480: 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a  ger in use..**.*
9490: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
94a0: 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54  CNTL_SYNC]].** T
94b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
94c0: 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73  _SYNC] opcode is
94d0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
94e0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20  nally by SQLite 
94f0: 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74  and.** sent to t
9500: 68 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65  he VFS immediate
9510: 6c 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53  ly before the xS
9520: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  ync method is in
9530: 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61  voked on a.** da
9540: 74 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63  tabase file desc
9550: 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74  riptor. Or, if t
9560: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
9570: 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a  is not invoked .
9580: 2a 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75  ** because the u
9590: 73 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72  ser has configur
95a0: 65 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a  ed SQLite with .
95b0: 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  ** [PRAGMA synch
95c0: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
95d0: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
95e0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69   it is invoked i
95f0: 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74  n place .** of t
9600: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e  he xSync method.
9610: 20 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20   In most cases, 
9620: 74 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  the pointer argu
9630: 6d 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68  ment passed with
9640: 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  .** this file-co
9650: 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48  ntrol is NULL. H
9660: 6f 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64  owever, if the d
9670: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
9680: 62 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20  being synced.** 
9690: 61 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c  as part of a mul
96a0: 74 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d  ti-database comm
96b0: 69 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74  it, the argument
96c0: 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c   points to a nul
96d0: 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
96e0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67  tring containing
96f0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
9700: 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c  s master-journal
9710: 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65   file name. VFSe
9720: 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f  s that .** do no
9730: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9740: 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  al should silent
9750: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
9760: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
9770: 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ons .** should n
9780: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
9790: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
97a0: 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64   with this opcod
97b0: 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61  e as doing so ma
97c0: 79 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68  y .** disrupt th
97d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
97e0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
97f0: 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71  FSes that do req
9800: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
9810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9820: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
9830: 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  TWO]].** The [SQ
9840: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49  LITE_FCNTL_COMMI
9850: 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f  T_PHASETWO] opco
9860: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
9870: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
9880: 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74  Lite.** and sent
9890: 20 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65   to the VFS afte
98a0: 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  r a transaction 
98b0: 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74  has been committ
98c0: 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ed immediately.*
98d0: 2a 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65  * but before the
98e0: 20 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c   database is unl
98f0: 6f 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61  ocked. VFSes tha
9900: 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  t do not need th
9910: 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f  is signal.** sho
9920: 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e  uld silently ign
9930: 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e  ore this opcode.
9940: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
9950: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a  ould not call.**
9960: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9970: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9980: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9990: 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75  ing so may disru
99a0: 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61  pt the .** opera
99b0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
99c0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
99d0: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
99e0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
99f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9a00: 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a  32_AV_RETRY]].**
9a10: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9a20: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
9a30: 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  RY] opcode is us
9a40: 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20  ed to configure 
9a50: 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74  automatic.** ret
9a60: 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e  ry counts and in
9a70: 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74  tervals for cert
9a80: 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65  ain disk I/O ope
9a90: 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a  rations for the.
9aa0: 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d  ** windows [VFS]
9ab0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
9ac0: 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20  vide robustness 
9ad0: 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  in the presence 
9ae0: 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73  of.** anti-virus
9af0: 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64   programs.  By d
9b00: 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64  efault, the wind
9b10: 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74  ows VFS will ret
9b20: 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a  ry file read,.**
9b30: 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64   file write, and
9b40: 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65   file delete ope
9b50: 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30  rations up to 10
9b60: 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64   times, with a d
9b70: 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69  elay.** of 25 mi
9b80: 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72  lliseconds befor
9b90: 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72  e the first retr
9ba0: 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64  y and with the d
9bb0: 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a  elay increasing.
9bc0: 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f  ** by an additio
9bd0: 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f  nal 25 milliseco
9be0: 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75  nds with each su
9bf0: 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20  bsequent retry. 
9c00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
9c10: 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f  allows these two
9c20: 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72   values (10 retr
9c30: 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69  ies and 25 milli
9c40: 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79  seconds of delay
9c50: 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73  ).** to be adjus
9c60: 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73  ted.  The values
9c70: 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72   are changed for
9c80: 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f   all database co
9c90: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  nnections.** wit
9ca0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f  hin the same pro
9cb0: 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d  cess.  The argum
9cc0: 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
9cd0: 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20   to an array of 
9ce0: 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  two.** integers 
9cf0: 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20  where the first 
9d00: 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65  integer i the ne
9d10: 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e  w retry count an
9d20: 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  d the second.** 
9d30: 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64  integer is the d
9d40: 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72  elay.  If either
9d50: 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61   integer is nega
9d60: 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73  tive, then the s
9d70: 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74  etting.** is not
9d80: 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73   changed but ins
9d90: 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76  tead the prior v
9da0: 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74  alue of that set
9db0: 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a  ting is written.
9dc0: 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61  ** into the arra
9dd0: 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e  y entry, allowin
9de0: 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65  g the current re
9df0: 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20  try settings to 
9e00: 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74  be.** interrogat
9e10: 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65  ed.  The zDbName
9e20: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67   parameter is ig
9e30: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  nored..**.** <li
9e40: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9e50: 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a  PERSIST_WAL]].**
9e60: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9e70: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
9e80: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
9e90: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
9ea0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
9eb0: 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41  t [WAL | Write A
9ec0: 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e  head Log] settin
9ed0: 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  g.  By default, 
9ee0: 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a  the auxiliary.**
9ef0: 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67   write ahead log
9f00: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
9f10: 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f  ry files used fo
9f20: 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f  r transaction co
9f30: 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74  ntrol.** are aut
9f40: 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
9f50: 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65  ed when the late
9f60: 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  st connection to
9f70: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
9f80: 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e   closes.  Settin
9f90: 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  g persistent WAL
9fa0: 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f   mode causes tho
9fb0: 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73  se files to pers
9fc0: 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f  ist after.** clo
9fd0: 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20  se.  Persisting 
9fe0: 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65  the files is use
9ff0: 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70  ful when other p
a000: 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f  rocesses that do
a010: 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69   not.** have wri
a020: 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e  te permission on
a030: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63   the directory c
a040: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61  ontaining the da
a050: 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74  tabase file want
a060: 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20  .** to read the 
a070: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61  database file, a
a080: 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68  s the WAL and sh
a090: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a0a0: 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20  s must exist.** 
a0b0: 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65  in order for the
a0c0: 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   database to be 
a0d0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66  readable.  The f
a0e0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a0f0: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
a100: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
a110: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
a120: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
a130: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
a140: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
a150: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
a160: 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c  e persistent WAL
a170: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a180: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a  able persistent.
a190: 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66  ** WAL mode.  If
a1a0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a1b0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a1c0: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a1d0: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57  the current.** W
a1e0: 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73  AL persistence s
a1f0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a200: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a210: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
a220: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a230: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57  SQLITE_FCNTL_POW
a240: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a250: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
a260: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
a270: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
a280: 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76  nt "powersafe-ov
a290: 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f  erwrite" or "PSO
a2a0: 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65  W" setting.  The
a2b0: 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a   PSOW setting.**
a2c0: 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
a2d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f  [SQLITE_IOCAP_PO
a2e0: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a2f0: 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a  E] bit of the.**
a300: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
a310: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e  ristics methods.
a320: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
a330: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
a340: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
a350: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
a360: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
a370: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
a380: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
a390: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
a3a0: 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d  disable zero-dam
a3b0: 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  age mode or 1 to
a3c0: 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d   enable zero-dam
a3d0: 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66  age.** mode.  If
a3e0: 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20   the integer is 
a3f0: 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f  -1, then it is o
a400: 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20  verwritten with 
a410: 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a  the current.** z
a420: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
a430: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
a440: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
a450: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  L_OVERWRITE]].**
a460: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
a470: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  NTL_OVERWRITE] o
a480: 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64  pcode is invoked
a490: 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72   by SQLite after
a4a0: 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72   opening.** a wr
a4b0: 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  ite transaction 
a4c0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a4d0: 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72  , unless it is r
a4e0: 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73  olled back for s
a4f0: 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74  ome.** reason, t
a500: 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61  he entire databa
a510: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  se file will be 
a520: 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74  overwritten by t
a530: 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74  he current .** t
a540: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73  ransaction. This
a550: 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55   is used by VACU
a560: 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  UM operations..*
a570: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a580: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a590: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a5a0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d  E_FCNTL_VFSNAME]
a5b0: 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75   opcode can be u
a5c0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
a5d0: 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c  e names of.** al
a5e0: 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65  l [VFSes] in the
a5f0: 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65   VFS stack.  The
a600: 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c   names are of al
a610: 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20  l VFS shims and 
a620: 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74  the.** final bot
a630: 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72  tom-level VFS ar
a640: 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  e written into m
a650: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
a660: 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rom .** [sqlite3
a670: 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74  _malloc()] and t
a680: 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f  he result is sto
a690: 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a  red in the char*
a6a0: 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61   variable.** tha
a6b0: 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  t the fourth par
a6c0: 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74  ameter of [sqlit
a6d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a6e0: 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a  )] points to..**
a6f0: 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72   The caller is r
a700: 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66  esponsible for f
a710: 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72  reeing the memor
a720: 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73  y when done.  As
a730: 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c   with.** all fil
a740: 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e  e-control action
a750: 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67  s, there is no g
a760: 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68  uarantee that th
a770: 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79  is will actually
a780: 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e  .** do anything.
a790: 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64    Callers should
a7a0: 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20   initialize the 
a7b0: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74  char* variable t
a7c0: 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  o a NULL.** poin
a7d0: 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73  ter in case this
a7e0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
a7f0: 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64   not implemented
a800: 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e  .  This file-con
a810: 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e  trol.** is inten
a820: 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74  ded for diagnost
a830: 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a  ic use only..**.
a840: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a850: 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45  FCNTL_VFS_POINTE
a860: 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  R]].** ^The [SQL
a870: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
a880: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69  INTER] opcode fi
a890: 6e 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  nds a pointer to
a8a0: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a   the top-level.*
a8b0: 2a 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e  * [VFSes] curren
a8c0: 74 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54  tly in use.  ^(T
a8d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e  he argument X in
a8e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  .** sqlite3_file
a8f0: 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49  _control(db,SQLI
a900: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a910: 4e 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a  NTER,X) must be.
a920: 2a 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c  ** of type "[sql
a930: 69 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20  ite3_vfs] **".  
a940: 54 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c  This opcodes wil
a950: 6c 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61  l set *X.** to a
a960: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
a970: 74 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e  top-level VFS.)^
a980: 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20  .** ^When there 
a990: 61 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53  are multiple VFS
a9a0: 20 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74   shims in the st
a9b0: 61 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65  ack, this opcode
a9c0: 20 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70   finds the.** up
a9d0: 70 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e  per-most shim on
a9e0: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
a9f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aa00: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
aa10: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
aa20: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
aa30: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
aa40: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
aa50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
aa60: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
aa70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
aa80: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
aa90: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
aaa0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
aab0: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
aac0: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
aad0: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
aae0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
aaf0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ab00: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
ab10: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
ab20: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
ab30: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
ab40: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
ab50: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
ab60: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
ab70: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
ab80: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
ab90: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
aba0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
abb0: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
abc0: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
abd0: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
abe0: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
abf0: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
ac00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ac10: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
ac20: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
ac30: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
ac40: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
ac50: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
ac60: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
ac70: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
ac80: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
ac90: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
aca0: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
acb0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
acc0: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
acd0: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
ace0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
acf0: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
ad00: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
ad10: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ad20: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ad30: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
ad40: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
ad50: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
ad60: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
ad70: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
ad80: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ad90: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
ada0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
adb0: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
adc0: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
add0: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
ade0: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
adf0: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
ae00: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
ae10: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
ae20: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
ae30: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
ae40: 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  if result string
ae50: 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61   is NULL, or tha
ae60: 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  t returns a copy
ae70: 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
ae80: 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20  t string if the 
ae90: 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55  string is non-NU
aea0: 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  LL..** ^If the [
aeb0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aec0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
aed0: 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79  l returns.** any
aee0: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68   result code oth
aef0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
af00: 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  OK] or [SQLITE_N
af10: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d  OTFOUND], that m
af20: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65  eans.** that the
af30: 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64   VFS encountered
af40: 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20   an error while 
af50: 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52  handling the [PR
af60: 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  AGMA] and the.**
af70: 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20   compilation of 
af80: 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73  the PRAGMA fails
af90: 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
afa0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
afb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
afc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75  ile control occu
afd0: 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e  rs at the beginn
afe0: 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74  ing of pragma st
aff0: 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73  atement analysis
b000: 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73   and so.** it is
b010: 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64   able to overrid
b020: 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47  e built-in [PRAG
b030: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  MA] statements..
b040: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b050: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b060: 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  DLER]].** ^The [
b070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b080: 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c  YHANDLER].** fil
b090: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
b0a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
b0b0: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
b0c0: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
b0d0: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
b0e0: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
b0f0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
b100: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
b110: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
b120: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
b130: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
b140: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
b150: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
b160: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
b170: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
b180: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
b190: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
b1a0: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
b1b0: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
b1c0: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
b1d0: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
b1e0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
b1f0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
b200: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
b210: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
b220: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
b230: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
b240: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
b250: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
b260: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
b270: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
b280: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
b290: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
b2a0: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
b2b0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
b2c0: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
b2d0: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
b2e0: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
b2f0: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
b300: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[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 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
b330: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
b340: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
b350: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
b360: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
b370: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
b380: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
b390: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
b3a0: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
b3b0: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
b3c0: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
b3d0: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
b3e0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
b3f0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
b400: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
b410: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
b420: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
b430: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
b440: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
b450: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
b460: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
b470: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
b480: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
b490: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
b4a0: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
b4b0: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
b4c0: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
b4d0: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
b4e0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
b4f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b500: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b510: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b520: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b530: 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
b540: 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72   is used to quer
b550: 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20  y or set the.** 
b560: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
b570: 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c  f bytes that wil
b580: 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65  l be used for me
b590: 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e  mory-mapped I/O.
b5a0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b5b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
b5c0: 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65   a value of type
b5d0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74   sqlite3_int64 t
b5e0: 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76  hat.** is an adv
b5f0: 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75  isory maximum nu
b600: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
b610: 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d   the file to mem
b620: 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a  ory map.  The.**
b630: 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72   pointer is over
b640: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
b650: 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65   old value.  The
b660: 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68   limit is not ch
b670: 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20  anged if.** the 
b680: 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79  value originally
b690: 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e   pointed to is n
b6a0: 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20  egative, and so 
b6b0: 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69  the current limi
b6c0: 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65  t .** can be que
b6d0: 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ried by passing 
b6e0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  in a pointer to 
b6f0: 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
b700: 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65  r.  This.** file
b710: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64  -control is used
b720: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69   internally to i
b730: 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41  mplement [PRAGMA
b740: 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a   mmap_size]..**.
b750: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b760: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a  FCNTL_TRACE]].**
b770: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b780: 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63  TL_TRACE] file c
b790: 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20  ontrol provides 
b7a0: 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61  advisory informa
b7b0: 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56  tion.** to the V
b7c0: 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68  FS about what th
b7d0: 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20  e higher layers 
b7e0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74  of the SQLite st
b7f0: 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a  ack are doing..*
b800: 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74  * This file cont
b810: 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73  rol is used by s
b820: 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79  ome VFS activity
b830: 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d   tracing [shims]
b840: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b850: 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t is a zero-term
b860: 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20  inated string.  
b870: 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e  Higher layers in
b880: 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73   the.** SQLite s
b890: 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74  tack may generat
b8a0: 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74  e instances of t
b8b0: 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  his file control
b8c0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49   if.** the [SQLI
b8d0: 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41  TE_USE_FCNTL_TRA
b8e0: 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  CE] compile-time
b8f0: 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c   option is enabl
b900: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
b910: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
b920: 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20  _MOVED]].** The 
b930: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b940: 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f  S_MOVED] file co
b950: 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73  ntrol interprets
b960: 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73   its argument as
b970: 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
b980: 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20   an integer and 
b990: 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c  it writes a bool
b9a0: 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  ean into that in
b9b0: 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a  teger depending.
b9c0: 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72  ** on whether or
b9d0: 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61   not the file ha
b9e0: 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20  s been renamed, 
b9f0: 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65  moved, or delete
ba00: 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61  d since it.** wa
ba10: 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a  s first opened..
ba20: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
ba30: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
ba40: 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54  ET_HANDLE]].** T
ba50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ba60: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
ba70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
ba80: 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e  d for debugging.
ba90: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
baa0: 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c   causes the xFil
bab0: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20  eControl method 
bac0: 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65  to swap the file
bad0: 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65   handle with the
bae0: 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20   one.** pointed 
baf0: 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61  to by the pArg a
bb00: 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63  rgument.  This c
bb10: 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65  apability is use
bb20: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
bb30: 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  .** and only nee
bb40: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
bb50: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
bb60: 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a  EST is defined..
bb70: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bb80: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
bb90: 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CK]].** The [SQL
bba0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
bbb0: 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c  OCK] is a signal
bbc0: 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65   to the VFS laye
bbd0: 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a  r that it might.
bbe0: 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f  ** be advantageo
bbf0: 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74  us to block on t
bc00: 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b  he next WAL lock
bc10: 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20   if the lock is 
bc20: 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a  not immediately.
bc30: 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54  ** available.  T
bc40: 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d  he WAL subsystem
bc50: 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67   issues this sig
bc60: 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a  nal during rare.
bc70: 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  ** circumstances
bc80: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78   in order to fix
bc90: 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20   a problem with 
bca0: 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69  priority inversi
bcb0: 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  on..** Applicati
bcc0: 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e  ons should <em>n
bcd0: 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73  ot</em> use this
bce0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a   file-control..*
bcf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bd00: 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d  E_FCNTL_ZIPVFS]]
bd10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bd20: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70  FCNTL_ZIPVFS] op
bd30: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
bd40: 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e  ted by zipvfs on
bd50: 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a  ly. All other.**
bd60: 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75   VFS should retu
bd70: 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  rn SQLITE_NOTFOU
bd80: 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  ND for this opco
bd90: 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  de..**.** <li>[[
bda0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
bdb0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
bdc0: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63  E_FCNTL_RBU] opc
bdd0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
bde0: 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61  ed by the specia
bdf0: 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a  l VFS used by.**
be00: 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69   the RBU extensi
be10: 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74  on only.  All ot
be20: 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72  her VFS should r
be30: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54  eturn SQLITE_NOT
be40: 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69  FOUND for.** thi
be50: 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c  s opcode.  .** <
be60: 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /ul>.*/.#define 
be70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
be80: 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20  KSTATE          
be90: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
bea0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
beb0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bec0: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
bed0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c  LITE_FCNTL_SET_L
bee0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
bef0: 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
bf00: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
bf10: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bf20: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
bf30: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
bf40: 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NT              
bf50: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
bf60: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
bf70: 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
bf80: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
bf90: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
bfa0: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37  TER            7
bfb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bfc0: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
bfd0: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a  ED            8.
bfe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bff0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
c000: 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23  TRY          9.#
c010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c020: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20  NTL_PERSIST_WAL 
c030: 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
c040: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c050: 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  TL_OVERWRITE    
c060: 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65            11.#de
c070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c080: 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20  L_VFSNAME       
c090: 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66           12.#def
c0a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c0b0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
c0c0: 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69  RITE    13.#defi
c0d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c0e0: 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
c0f0: 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e         14.#defin
c100: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42  e SQLITE_FCNTL_B
c110: 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20  USYHANDLER      
c120: 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65        15.#define
c130: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45   SQLITE_FCNTL_TE
c140: 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20  MPFILENAME      
c150: 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20       16.#define 
c160: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
c170: 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  P_SIZE          
c180: 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53      18.#define S
c190: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
c1a0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c1b0: 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51     19.#define SQ
c1c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d  LITE_FCNTL_HAS_M
c1d0: 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20  OVED            
c1e0: 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    20.#define SQL
c1f0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20  ITE_FCNTL_SYNC  
c200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c210: 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   21.#define SQLI
c220: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c230: 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20  PHASETWO        
c240: 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  22.#define SQLIT
c250: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
c260: 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32  T_HANDLE       2
c270: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
c280: 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b  _FCNTL_WAL_BLOCK
c290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
c2a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c2b0: 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20  FCNTL_ZIPVFS    
c2c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a               25.
c2d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c2e0: 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20  CNTL_RBU        
c2f0: 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23              26.#
c300: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c310: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20  NTL_VFS_POINTER 
c320: 20 20 20 20 20 20 20 20 20 20 20 32 37 0a 23 64             27.#d
c330: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c340: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
c350: 45 52 20 20 20 20 20 20 20 20 32 38 0a 0a 2f 2a  ER        28../*
c360: 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65   deprecated name
c370: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
c380: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
c390: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
c3a0: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
c3b0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
c3c0: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
c3d0: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c3e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
c3f0: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
c400: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
c410: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c420: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c430: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f  L_LAST_ERRNO.../
c440: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c450: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
c460: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
c470: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
c480: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
c490: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
c4a0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
c4b0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
c4c0: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
c4d0: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
c4e0: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
c4f0: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
c500: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
c510: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
c520: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
c530: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
c540: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
c550: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
c560: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
c570: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
c580: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
c590: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
c5a0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
c5b0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
c5c0: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
c5d0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
c5e0: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
c5f0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c600: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c610: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
c620: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
c630: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
c640: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
c650: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
c660: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
c670: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
c680: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
c690: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
c6a0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
c6b0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
c6c0: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
c6d0: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
c6e0: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
c6f0: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
c700: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
c710: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
c720: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
c730: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
c740: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
c750: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
c760: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
c770: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
c780: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
c790: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
c7a0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
c7b0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
c7c0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
c7d0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
c7e0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
c7f0: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
c800: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
c810: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
c820: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
c830: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
c840: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
c850: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
c860: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
c870: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
c880: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
c890: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
c8a0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
c8b0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
c8c0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
c8d0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
c8e0: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
c8f0: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
c900: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
c910: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
c920: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
c930: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
c940: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
c950: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
c960: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
c970: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
c980: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
c990: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
c9a0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
c9b0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
c9c0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
c9d0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
c9e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
c9f0: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
ca00: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
ca10: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
ca20: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
ca30: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
ca40: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
ca50: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
ca60: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
ca70: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
ca80: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
ca90: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
caa0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
cab0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
cac0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
cad0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
cae0: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
caf0: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
cb00: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
cb10: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
cb20: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
cb30: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
cb40: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
cb50: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
cb60: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
cb70: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
cb80: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
cb90: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
cba0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
cbb0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
cbc0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
cbd0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
cbe0: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
cbf0: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
cc00: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
cc10: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
cc20: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
cc30: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
cc40: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
cc50: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
cc60: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
cc70: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
cc80: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
cc90: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
cca0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
ccb0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
ccc0: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
ccd0: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
cce0: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
ccf0: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cd00: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
cd10: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
cd20: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
cd30: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
cd40: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
cd50: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
cd60: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
cd70: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
cd80: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
cd90: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
cda0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
cdb0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
cdc0: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
cdd0: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
cde0: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
cdf0: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
ce00: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
ce10: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
ce20: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
ce30: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
ce40: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
ce50: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
ce60: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
ce70: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
ce80: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
ce90: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
cea0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
ceb0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
cec0: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
ced0: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
cee0: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
cef0: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
cf00: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
cf10: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
cf20: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
cf30: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
cf40: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
cf50: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
cf60: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
cf70: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
cf80: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
cf90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
cfa0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
cfb0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
cfc0: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
cfd0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
cfe0: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
cff0: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
d000: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
d010: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
d020: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
d030: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
d040: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
d050: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
d060: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d070: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
d080: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
d090: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
d0a0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
d0b0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
d0c0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
d0d0: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
d0e0: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
d0f0: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
d100: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
d110: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
d120: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d130: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d140: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
d150: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
d160: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
d170: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
d180: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d190: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
d1a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d1b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
d1c0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d1d0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
d1e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d1f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
d200: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d210: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
d220: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
d230: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d240: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
d250: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d260: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
d270: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d280: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
d290: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
d2a0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
d2b0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
d2c0: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
d2d0: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
d2e0: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
d2f0: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
d300: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
d310: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
d320: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
d330: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
d340: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
d350: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
d360: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
d370: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
d380: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
d390: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
d3a0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
d3b0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
d3c0: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
d3d0: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
d3e0: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
d3f0: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
d400: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d410: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
d420: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
d430: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
d440: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
d450: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
d460: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
d470: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
d480: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
d490: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
d4a0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
d4b0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
d4c0: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
d4d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
d4e0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
d4f0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
d500: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
d510: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d520: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
d530: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d540: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
d550: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
d560: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
d570: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
d580: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d590: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
d5a0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
d5b0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
d5c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d5d0: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
d5e0: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
d5f0: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
d600: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
d610: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
d620: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
d630: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
d640: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d650: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
d660: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
d670: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
d680: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
d690: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
d6a0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
d6b0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
d6c0: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
d6d0: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
d6e0: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
d6f0: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
d700: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
d710: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
d720: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
d730: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
d740: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
d750: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
d760: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
d770: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
d780: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
d790: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
d7a0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
d7b0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
d7c0: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
d7d0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
d7e0: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
d7f0: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
d800: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
d810: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
d820: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
d830: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
d840: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
d850: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
d860: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
d870: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
d880: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
d890: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
d8a0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
d8b0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
d8c0: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
d8d0: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
d8e0: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
d8f0: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
d900: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
d910: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
d920: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
d930: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
d940: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
d950: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
d960: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
d970: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
d980: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
d990: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
d9a0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
d9b0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
d9c0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d9d0: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
d9e0: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
d9f0: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
da00: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
da10: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
da20: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
da30: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
da40: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
da50: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
da60: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
da70: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
da80: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
da90: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
daa0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
dab0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
dac0: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
dad0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
dae0: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
daf0: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
db00: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
db10: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
db20: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
db30: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
db40: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
db50: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
db60: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
db70: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
db80: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
db90: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
dba0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
dbb0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
dbc0: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
dbd0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
dbe0: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
dbf0: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
dc00: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dc10: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
dc20: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
dc30: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
dc40: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
dc50: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dc60: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
dc70: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
dc80: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
dc90: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
dca0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
dcb0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
dcc0: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
dcd0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
dce0: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
dcf0: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
dd00: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
dd10: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
dd20: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
dd30: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
dd40: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
dd50: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
dd60: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
dd70: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dd80: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
dd90: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
dda0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
ddb0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
ddc0: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
ddd0: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
dde0: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
ddf0: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
de00: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
de10: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
de20: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
de30: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
de40: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
de50: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
de60: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
de70: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
de80: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
de90: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
dea0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
deb0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
dec0: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
ded0: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
dee0: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
def0: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
df00: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
df10: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
df20: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
df30: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
df40: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
df50: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
df60: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
df70: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
df80: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
df90: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
dfa0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
dfb0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
dfc0: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
dfd0: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
dfe0: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
dff0: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
e000: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
e010: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
e020: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
e030: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
e040: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
e050: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
e060: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
e070: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
e080: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
e090: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
e0a0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
e0b0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
e0c0: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
e0d0: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
e0e0: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
e0f0: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
e100: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
e110: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
e120: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
e130: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
e140: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
e150: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
e160: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
e170: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
e180: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
e190: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
e1a0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
e1b0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
e1c0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
e1d0: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
e1e0: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
e1f0: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
e200: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
e210: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
e220: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
e230: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
e240: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
e250: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
e260: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
e270: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
e280: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
e290: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
e2a0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
e2b0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
e2c0: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
e2d0: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
e2e0: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
e2f0: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
e300: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
e310: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
e320: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
e330: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
e340: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
e350: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
e360: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
e370: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
e380: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
e390: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
e3a0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
e3b0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
e3c0: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
e3d0: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
e3e0: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
e3f0: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
e400: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
e410: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
e420: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
e430: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
e440: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
e450: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
e460: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
e470: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
e480: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
e490: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
e4a0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
e4b0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
e4c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e4d0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
e4e0: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
e4f0: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
e500: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
e510: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
e520: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
e530: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
e540: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
e550: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
e560: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
e570: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
e580: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
e590: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
e5a0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
e5b0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
e5c0: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
e5d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e5e0: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
e5f0: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
e600: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
e610: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
e620: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
e630: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
e640: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
e650: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
e660: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
e670: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e680: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
e690: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
e6a0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
e6b0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
e6c0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
e6d0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e6e0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e6f0: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
e700: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
e710: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e720: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e730: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
e740: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
e750: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
e760: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e780: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
e790: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
e7a0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
e7b0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e7c0: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
e7d0: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
e7e0: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
e7f0: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
e800: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
e810: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
e820: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
e830: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
e840: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
e850: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
e860: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
e870: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
e880: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
e890: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e8a0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e8b0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
e8c0: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
e8d0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
e8e0: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
e8f0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
e900: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
e910: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
e920: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
e930: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e940: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
e950: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e960: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e970: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
e980: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e990: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
e9a0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
e9b0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
e9c0: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
e9d0: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
e9e0: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
e9f0: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
ea00: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
ea10: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
ea20: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
ea30: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
ea40: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
ea50: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
ea60: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
ea70: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
ea80: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
ea90: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
eaa0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
eab0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
eac0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ead0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
eae0: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
eaf0: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
eb00: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
eb10: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
eb20: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
eb30: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
eb40: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
eb50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
eb60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
eb70: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
eb80: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
eb90: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
eba0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
ebb0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
ebc0: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
ebd0: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
ebe0: 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  nded in future v
ebf0: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
ec00: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
ec10: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
ec20: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
ec30: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
ec40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ec50: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
ec60: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
ec70: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ec80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
ec90: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
eca0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
ecb0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
ecc0: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
ecd0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
ece0: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
ecf0: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
ed00: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
ed10: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
ed20: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
ed30: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
ed40: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ed50: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
ed60: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
ed70: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
ed80: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
ed90: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
eda0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
edb0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
edc0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
edd0: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
ede0: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
edf0: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
ee00: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
ee10: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ee20: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
ee30: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
ee40: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
ee50: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
ee60: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
ee70: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ee80: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
ee90: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
eea0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
eeb0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
eec0: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
eed0: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
eee0: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
eef0: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
ef00: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
ef10: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ef20: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
ef30: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ef40: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
ef50: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
ef60: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ef70: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
ef80: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
ef90: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
efa0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
efb0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
efc0: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
efd0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
efe0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
eff0: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
f000: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
f010: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
f020: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
f030: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f040: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
f050: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
f060: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
f070: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
f080: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
f090: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
f0a0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
f0b0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
f0c0: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
f0d0: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
f0e0: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
f0f0: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
f100: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f110: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
f120: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
f130: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
f140: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
f150: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
f160: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
f170: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
f180: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
f190: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f1a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f1b0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f1c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
f1d0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f1e0: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
f1f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f200: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
f210: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
f220: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f230: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f240: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
f250: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
f260: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
f270: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
f280: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
f290: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
f2a0: 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
f2b0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
f2c0: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
f2d0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f2e0: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
f2f0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f300: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
f310: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f320: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
f330: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
f340: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
f350: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
f360: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
f370: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
f380: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
f390: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f3a0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
f3b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f3c0: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
f3d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f3e0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
f3f0: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
f400: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
f410: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
f420: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
f430: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
f440: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
f450: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
f460: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
f470: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
f480: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
f490: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
f4a0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
f4b0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
f4c0: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
f4d0: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
f4e0: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
f4f0: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
f500: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
f510: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
f520: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
f530: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
f540: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
f550: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f560: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f570: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
f580: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
f590: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
f5a0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
f5b0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
f5c0: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
f5d0: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
f5e0: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
f5f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
f600: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
f610: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
f620: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
f630: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
f640: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
f650: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
f660: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
f670: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
f680: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
f690: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
f6a0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
f6b0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
f6c0: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
f6d0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
f6e0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
f6f0: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
f700: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
f710: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
f720: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f730: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
f740: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
f750: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
f760: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
f770: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
f780: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f790: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f7a0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
f7b0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f7c0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
f7d0: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
f7e0: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
f7f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f800: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
f810: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
f820: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
f830: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f840: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
f850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f860: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
f870: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
f880: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
f890: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
f8a0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
f8b0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
f8c0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f8d0: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
f8e0: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f8f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f900: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
f910: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
f920: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
f930: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
f940: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f950: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f960: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
f970: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f980: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
f990: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
f9a0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
f9b0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
f9c0: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
f9d0: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
f9e0: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
f9f0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
fa00: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
fa10: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
fa20: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
fa30: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
fa40: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
fa50: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
fa60: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
fa70: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
fa80: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
fa90: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
faa0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
fab0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
fac0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fad0: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
fae0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
faf0: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
fb00: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fb10: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
fb20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fb30: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
fb40: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fb50: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
fb60: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
fb70: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
fb80: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
fb90: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
fba0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
fbb0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
fbc0: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
fbd0: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
fbe0: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
fbf0: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
fc00: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
fc10: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
fc20: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
fc30: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
fc40: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
fc50: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
fc60: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
fc70: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
fc80: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
fc90: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
fca0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
fcb0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
fcc0: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
fcd0: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
fce0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
fcf0: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fd00: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
fd10: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
fd20: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
fd30: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fd40: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
fd50: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
fd60: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
fd70: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
fd80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
fd90: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
fda0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
fdb0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
fdc0: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
fdd0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
fde0: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
fdf0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
fe00: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
fe10: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
fe20: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
fe30: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
fe40: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fe50: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
fe60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fe70: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
fe80: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fe90: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
fea0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
feb0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
fec0: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
fed0: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
fee0: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
fef0: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
ff00: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
ff10: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
ff20: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
ff30: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
ff40: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
ff50: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
ff60: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
ff70: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
ff80: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
ff90: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
ffa0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
ffb0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
ffc0: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
ffd0: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
ffe0: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
fff0: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
10000 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
10010 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
10020 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
10030 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
10040 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
10050 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
10060 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
10070 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
10080 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
10090 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
100a0 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
100b0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
100c0 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
100d0 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
100e0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
100f0 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
10100 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
10110 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
10120 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
10130 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
10140 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
10150 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
10160 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
10170 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
10180 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
10190 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
101a0 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
101b0 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
101c0 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
101d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
101e0 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
101f0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10200 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
10210 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
10220 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10230 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10240 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
10250 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
10260 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
10270 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
10280 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
10290 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
102a0 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
102b0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
102c0 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
102d0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
102e0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
102f0 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
10300 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
10310 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
10320 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10330 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
10340 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
10350 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
10360 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
10370 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
10380 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
10390 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
103a0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
103b0 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
103c0 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
103d0 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
103e0 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
103f0 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
10400 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
10410 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
10420 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
10430 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
10440 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
10450 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
10460 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
10470 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10480 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
10490 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
104a0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
104b0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
104c0 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
104d0 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
104e0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
104f0 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
10500 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
10510 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
10520 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
10530 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
10540 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  .int sqlite3_ini
10550 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69  tialize(void);.i
10560 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  nt sqlite3_shutd
10570 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  own(void);.int s
10580 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
10590 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
105a0 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
105b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
105c0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
105d0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
105e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
105f0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
10600 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10610 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10620 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10630 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10640 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10650 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10660 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10670 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10680 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10690 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
106a0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
106b0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
106c0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
106d0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
106e0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
106f0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
10700 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
10710 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10720 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10730 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10740 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10750 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10760 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10770 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10780 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10790 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
107a0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
107b0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
107c0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
107d0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
107e0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
107f0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
10800 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10810 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10820 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10830 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10840 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10850 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10860 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10870 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10880 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10890 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
108a0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
108b0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
108c0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
108d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
108e0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
108f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10900 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10910 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10920 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10930 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10940 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10950 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10960 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10970 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10980 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10990 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
109a0 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
109b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
109c0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
109d0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
109e0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
109f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10a00 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10a10 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10a20 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10a30 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10a40 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10a50 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10a60 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10a70 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10a80 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10a90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10aa0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10ab0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ac0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10ad0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10ae0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10af0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10b00 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10b10 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10b20 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10b30 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10b40 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10b50 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10b60 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69  rror code]..*/.i
10b70 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
10b80 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
10b90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10ba0 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
10bb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
10bc0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
10bd0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10be0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
10bf0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10c00 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
10c10 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10c20 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10c30 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10c40 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
10c50 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10c60 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10c70 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10c80 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10c90 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10ca0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10cb0 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10cc0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10cd0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
10ce0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10cf0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10d00 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
10d10 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10d20 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10d30 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10d40 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10d50 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10d60 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10d70 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10d80 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10d90 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10da0 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10db0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10dc0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
10dd0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
10de0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
10df0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
10e00 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10e10 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
10e20 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
10e30 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
10e40 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
10e50 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  cessful..*/.int 
10e60 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10e70 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
10e80 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
10e90 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10ea0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
10eb0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
10ec0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10ed0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
10ee0 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
10ef0 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
10f00 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
10f10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
10f20 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
10f30 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
10f40 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
10f50 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
10f60 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
10f70 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
10f80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
10f90 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
10fa0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
10fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10fc0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
10fd0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10fe0 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
10ff0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11000 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11010 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11020 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11030 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11040 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11050 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11060 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11070 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11080 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
11090 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
110a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
110b0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
110c0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
110d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
110e0 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
110f0 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11100 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11110 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11120 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11130 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11140 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11150 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11160 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11170 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
11180 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
11190 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
111a0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
111b0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
111c0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
111d0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
111e0 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
111f0 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11200 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11210 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11220 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11230 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11240 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11250 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11260 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11270 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
11280 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
11290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
112a0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
112b0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
112c0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
112d0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
112e0 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
112f0 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11300 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11310 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11320 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11330 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11340 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11350 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11360 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11370 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
11380 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
11390 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
113a0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
113b0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
113c0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
113d0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
113e0 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
113f0 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11400 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11410 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11420 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11430 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11440 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11450 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11460 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11470 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
11480 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
11490 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
114a0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
114b0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
114c0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
114d0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
114e0 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
114f0 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11500 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11510 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11520 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11530 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11540 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11550 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11560 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11570 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
11580 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
11590 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
115a0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
115b0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
115c0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
115d0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
115e0 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
115f0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11600 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11610 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11620 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11630 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11640 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11650 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11660 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11670 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
11680 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
11690 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
116a0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
116b0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
116c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
116d0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
116e0 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
116f0 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11700 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11710 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11720 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11730 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11740 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11750 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11760 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11770 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
11780 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11790 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
117a0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
117b0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
117c0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
117d0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
117e0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
117f0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11800 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11810 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11820 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11830 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11840 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11850 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11860 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11870 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
11880 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
11890 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
118a0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
118b0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
118c0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
118d0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
118e0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
118f0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11900 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11910 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11920 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11930 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11940 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11950 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11960 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11970 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11980 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11990 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
119a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
119b0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
119c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
119d0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
119e0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
119f0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11a00 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11a10 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11a20 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11a30 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11a40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11a50 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11a60 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11a70 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11a80 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11a90 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11aa0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11ab0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11ac0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11ad0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11ae0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11af0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11b00 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11b10 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11b20 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11b30 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11b40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11b50 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11b60 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11b70 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11b80 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11b90 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11ba0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11bb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11bc0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11bd0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11be0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11bf0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11c00 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11c10 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11c20 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11c30 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11c40 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11c50 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11c60 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11c70 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11c80 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11c90 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11ca0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11cb0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11cc0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11cd0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11ce0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11cf0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11d00 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
11d10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11d20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
11d30 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
11d40 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
11d50 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11d60 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11d70 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11d80 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11d90 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11da0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11db0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11dc0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11dd0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11de0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11df0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e00 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
11e10 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
11e20 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11e30 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11e40 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
11e50 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11e60 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
11e70 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11e80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11e90 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
11ea0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
11eb0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
11ec0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
11ed0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
11ee0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
11ef0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
11f00 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
11f10 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
11f20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
11f30 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
11f40 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
11f50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
11f60 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
11f70 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
11f80 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
11f90 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11fa0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
11fb0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
11fc0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
11fd0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
11fe0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
11ff0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12000 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12010 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12020 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12030 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12040 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12050 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12060 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12070 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12080 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12090 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
120a0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
120b0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
120c0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
120d0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
120e0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
120f0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12100 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12110 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12120 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12130 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12140 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12150 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12160 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12170 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
12180 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
12190 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
121a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
121b0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
121c0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
121d0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
121e0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
121f0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12200 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12210 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12220 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12230 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12240 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12250 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12260 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12270 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
12280 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
12290 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
122a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
122b0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
122c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
122d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
122e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
122f0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12300 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12310 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12320 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12330 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12340 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12350 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12360 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12370 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
12380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12390 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
123a0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
123b0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
123c0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
123d0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
123e0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
123f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12400 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12410 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12420 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12430 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12440 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12450 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12460 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12470 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
12480 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
12490 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
124a0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
124b0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
124c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
124d0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
124e0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
124f0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12500 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12510 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12520 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12530 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12540 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12550 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12560 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12570 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
12580 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
12590 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
125a0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
125b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
125c0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
125d0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
125e0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
125f0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12600 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12610 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12620 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12630 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12640 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12650 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12660 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12670 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
12680 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
12690 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
126a0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
126b0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
126c0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
126d0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
126e0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
126f0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12700 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12710 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12720 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12730 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12740 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12750 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12760 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12770 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
12780 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12790 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
127a0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
127b0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
127c0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
127d0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
127e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
127f0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12810 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12820 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12830 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12840 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12850 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12860 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
12880 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
12890 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
128a0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
128b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
128c0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
128d0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
128e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
128f0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12900 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12910 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12920 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12930 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12940 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12950 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12960 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12970 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12980 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12990 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
129a0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
129b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
129c0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
129d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
129e0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12a00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12a10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12a20 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12a30 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12a40 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12a50 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12a60 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12a80 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12a90 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12aa0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12ab0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12ac0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12ad0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12ae0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12af0 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12b00 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12b10 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12b20 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12b30 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12b40 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12b50 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12b60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12b70 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12b80 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12b90 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12ba0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12bb0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12bc0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12bd0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12be0 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12bf0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12c00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12c10 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12c20 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12c30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12c40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12c50 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12c60 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12c70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12c80 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12c90 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
12ca0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12cb0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12cc0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12cd0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12ce0 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12cf0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12d00 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12d10 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12d20 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
12d30 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12d40 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12d50 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12d60 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
12d70 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
12d80 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12d90 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12da0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12db0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12dc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12dd0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12de0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12df0 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12e00 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12e10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12e20 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
12e30 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
12e40 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
12e50 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
12e60 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
12e70 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
12e80 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
12e90 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
12ea0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12eb0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
12ec0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12ed0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12ee0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
12ef0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
12f00 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
12f10 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
12f20 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
12f30 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12f40 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
12f50 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
12f60 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
12f70 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
12f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
12f90 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
12fa0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12fb0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
12fc0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
12fd0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
12fe0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12ff0 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13000 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13010 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13020 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13030 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13040 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13050 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13060 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13070 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
13080 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
13090 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
130a0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
130b0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
130c0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
130d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
130e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
130f0 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13100 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13110 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13120 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13130 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13140 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13150 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13160 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13170 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13180 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
13190 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
131a0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
131b0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
131c0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
131d0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
131e0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
131f0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13200 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13210 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13220 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13230 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13240 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13250 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13260 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13270 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
13280 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
13290 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
132a0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
132b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
132c0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
132d0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
132e0 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
132f0 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13300 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13310 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13320 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13330 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13340 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13350 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13360 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13370 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
13380 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
13390 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
133a0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
133b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
133c0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
133d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
133e0 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
133f0 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13400 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13410 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13420 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13430 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13440 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13450 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13460 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13470 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
13480 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
13490 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
134a0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
134b0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
134c0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
134d0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
134e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
134f0 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13500 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13510 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13520 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13530 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13540 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13550 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13560 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13570 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
13580 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13590 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
135a0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
135b0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
135c0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
135d0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
135e0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
135f0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13600 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13610 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13620 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13630 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13640 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13650 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13660 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13670 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13680 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13690 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
136a0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
136b0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
136c0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
136d0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
136e0 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
136f0 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13700 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13710 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13720 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13730 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13740 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13750 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13760 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13770 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
13780 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
13790 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
137a0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
137b0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
137c0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
137d0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
137e0 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
137f0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13800 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13810 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13820 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13830 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13840 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13850 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13860 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13870 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
13880 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
13890 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
138a0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
138b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
138c0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
138d0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
138e0 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
138f0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13900 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13910 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13920 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13930 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13940 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13950 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13960 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13970 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13980 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13990 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
139a0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
139b0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
139c0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
139d0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
139e0 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
139f0 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13a00 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13a10 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13a20 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13a30 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13a40 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13a50 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13a60 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13a70 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13a80 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13a90 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13aa0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13ab0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13ac0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13ad0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13ae0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13af0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13b00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13b10 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13b20 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13b30 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13b40 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13b50 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13b60 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13b70 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13b80 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13b90 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13ba0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13bb0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13bc0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13bd0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13be0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13bf0 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13c00 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13c10 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13c20 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13c30 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13c40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13c50 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13c60 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13c70 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13c80 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13c90 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13ca0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13cb0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13cc0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13cd0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13ce0 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13cf0 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13d00 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13d10 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13d20 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
13d30 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13d40 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
13d50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13d60 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
13d70 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
13d80 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13d90 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13da0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13db0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13dc0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13dd0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13de0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13df0 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13e00 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13e10 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13e20 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13e30 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
13e40 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13e50 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13e60 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13e70 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
13e80 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13e90 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13ea0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13eb0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13ec0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13ed0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13ee0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
13ef0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
13f00 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
13f10 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
13f20 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
13f30 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
13f40 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
13f50 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
13f60 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
13f70 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
13f80 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
13f90 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
13fa0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
13fb0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
13fc0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
13fd0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
13fe0 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
13ff0 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14000 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14010 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14020 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14030 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14040 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14050 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14060 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14070 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
14080 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
14090 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
140a0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
140b0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
140c0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
140d0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
140e0 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
140f0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14100 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14110 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14120 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14130 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14140 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14150 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14160 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14170 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
14180 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14190 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
141a0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
141b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
141c0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
141d0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
141e0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
141f0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14200 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14210 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14220 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14230 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14240 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14250 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14260 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14270 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
14280 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
14290 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
142a0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
142b0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
142c0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
142d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
142e0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
142f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14300 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14310 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14320 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14330 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14340 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14350 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14360 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14370 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
14380 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
14390 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
143a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
143b0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
143c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
143d0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
143e0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
143f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14400 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14420 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14430 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14440 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14450 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14460 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14470 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
14480 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14490 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
144a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
144b0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
144c0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
144d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
144e0 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
144f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14500 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14510 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14520 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14530 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14540 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14550 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14560 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14570 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
14580 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
14590 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
145a0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
145b0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
145c0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
145d0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
145e0 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
145f0 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14600 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14610 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14620 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14630 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14640 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14650 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14660 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14670 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
14680 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
14690 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
146a0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
146b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
146c0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
146d0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
146e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
146f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14700 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14710 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14720 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14730 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14740 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14750 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14760 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14770 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14780 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
14790 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
147a0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
147b0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
147c0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
147d0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
147e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
147f0 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14800 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14810 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14820 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14830 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14840 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14850 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14860 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14870 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
14880 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
14890 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
148a0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
148b0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
148c0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
148d0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
148e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
148f0 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14900 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14910 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14920 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14930 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14940 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14950 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14960 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14970 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14980 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
149a0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
149b0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
149c0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
149d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
149e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
149f0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14a00 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14a10 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14a20 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14a30 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14a40 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14a50 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14a60 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14a70 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14a80 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14a90 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14aa0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14ab0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14ac0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14ad0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14ae0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14af0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14b00 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14b10 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14b20 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14b30 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14b40 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14b50 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14b60 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14b70 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14b80 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14b90 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14ba0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14bb0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14bc0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14bd0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14be0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14bf0 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14c10 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14c20 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14c30 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14c40 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14c50 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14c60 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14c70 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14c80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14c90 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14ca0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14cb0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14cc0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14cd0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14ce0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14cf0 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14d00 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14d10 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14d20 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14d30 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
14d40 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
14d50 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
14d60 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
14d70 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
14d80 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14d90 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14da0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14db0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14dc0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14dd0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14de0 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14df0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14e00 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14e10 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
14e20 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
14e30 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
14e40 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14e50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14e60 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14e70 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
14e80 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
14e90 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
14ea0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14eb0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
14ec0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
14ed0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
14ee0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
14ef0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
14f00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
14f10 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
14f20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
14f30 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
14f40 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
14f50 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
14f60 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
14f70 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
14f80 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
14f90 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
14fa0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
14fb0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
14fc0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
14fd0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
14fe0 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
14ff0 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15000 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15010 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15020 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15030 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15040 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15050 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15060 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15070 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
15080 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
15090 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
150a0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
150b0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
150c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
150d0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
150e0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
150f0 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15100 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15110 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15120 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15130 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15140 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15150 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15160 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15170 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
15180 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
15190 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
151a0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
151b0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
151c0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
151d0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
151e0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
151f0 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15200 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15210 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15220 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15230 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15240 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15250 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15260 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15270 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
15280 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
15290 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
152a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
152b0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
152c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
152d0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
152e0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
152f0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15300 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15310 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15320 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15330 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15340 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15350 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15360 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15370 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
15380 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
15390 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
153a0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
153b0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
153c0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
153d0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
153e0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
153f0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15400 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15410 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15420 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15430 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15440 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15450 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15460 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15470 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15480 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
15490 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
154a0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
154b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
154c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
154d0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
154e0 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
154f0 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15500 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15510 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15520 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15530 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15540 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15550 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15560 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15570 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
15580 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
15590 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
155a0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
155b0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
155c0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
155d0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
155e0 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
155f0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15600 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15610 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15620 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15630 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15640 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15650 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15660 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15670 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
15680 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15690 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
156a0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
156b0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
156c0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
156d0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
156e0 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
156f0 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15700 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15710 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15720 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15730 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15740 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15750 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15760 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15770 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
15780 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
15790 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
157a0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
157b0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
157c0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
157d0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
157e0 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
157f0 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15800 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15810 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15820 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15830 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15840 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15850 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15860 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15870 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
15880 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
15890 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
158a0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
158b0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
158c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
158d0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
158e0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
158f0 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15900 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15910 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15920 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15930 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15940 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15950 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15960 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15970 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15980 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15990 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
159a0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
159b0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
159c0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
159d0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
159e0 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
159f0 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15a00 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15a10 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15a20 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15a30 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15a40 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15a50 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15a60 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15a70 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15a80 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15a90 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15aa0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15ab0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15ac0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15ad0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15ae0 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15af0 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15b00 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15b10 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15b20 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15b30 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15b40 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15b50 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15b60 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15b70 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15b80 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15b90 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15ba0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15bb0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15bc0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15bd0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15be0 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15bf0 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15c00 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15c10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15c20 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15c30 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15c40 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15c50 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15c60 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15c70 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15c80 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15c90 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15ca0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15cb0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15cc0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15cd0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15ce0 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15cf0 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15d00 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15d10 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15d20 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15d30 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15d40 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15d50 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15d60 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15d70 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15d80 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15d90 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15da0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15db0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15dc0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15dd0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15de0 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15df0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15e00 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15e10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
15e20 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
15e30 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
15e40 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
15e50 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15e60 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
15e70 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
15e80 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
15e90 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
15ea0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
15eb0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
15ec0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15ed0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
15ee0 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
15ef0 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
15f00 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
15f10 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
15f20 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
15f30 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
15f40 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
15f50 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
15f60 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
15f70 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
15f80 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15f90 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15fa0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15fb0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15fc0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
15fd0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15fe0 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
15ff0 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16000 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16010 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16020 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16030 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16040 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16050 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16060 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16070 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
16080 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
16090 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
160a0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
160b0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
160c0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
160d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
160e0 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
160f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16100 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16110 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16120 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16130 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16140 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16150 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16160 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16170 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
16180 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
16190 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
161a0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
161b0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
161c0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
161d0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
161e0 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
161f0 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16200 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16210 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16220 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16230 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16240 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16250 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16260 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16270 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
16280 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
16290 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
162a0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
162b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
162c0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
162d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
162e0 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
162f0 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16300 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16310 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16320 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16330 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16340 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16350 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16360 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16370 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
16380 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
16390 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
163a0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
163b0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
163c0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
163d0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
163e0 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
163f0 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16400 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16410 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16420 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16430 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16440 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16450 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16460 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16470 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
16480 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
16490 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
164a0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
164b0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
164c0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
164d0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a   this value..**.
164e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
164f0 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c  IG_STMTJRNL_SPIL
16500 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  L]].** <dt>SQLIT
16510 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16520 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e  L_SPILL.** <dd>^
16530 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16540 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  G_STMTJRNL_SPILL
16550 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16560 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16570 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65   which.** become
16580 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74  s the [statement
16590 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d   journal] spill-
165a0 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c  to-disk threshol
165b0 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65  d.  .** [Stateme
165c0 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65  nt journals] are
165d0 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
165e0 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65  until their size
165f0 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65   (in bytes).** e
16600 78 63 65 65 64 73 20 74 68 69 73 20 74 68 72 65  xceeds this thre
16610 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20  shold, at which 
16620 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65 20 77  point they are w
16630 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a  ritten to disk..
16640 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74 68 72  ** Or if the thr
16650 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74  eshold is -1, st
16660 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73  atement journals
16670 20 61 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64   are always held
16680 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20  .** exclusively 
16690 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69  in memory..** Si
166a0 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65  nce many stateme
166b0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65  nt journals neve
166c0 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20  r become large, 
166d0 73 65 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c  setting the spil
166e0 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74  l.** threshold t
166f0 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68 20 61  o a value such a
16700 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61  s 64KiB can grea
16710 74 6c 79 20 72 65 64 75 63 65 20 74 68 65 20 61  tly reduce the a
16720 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20  mount of.** I/O 
16730 72 65 71 75 69 72 65 64 20 74 6f 20 73 75 70 70  required to supp
16740 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f  ort statement ro
16750 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64  llback..** The d
16760 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72  efault value for
16770 20 74 68 69 73 20 73 65 74 74 69 6e 67 20 69 73   this setting is
16780 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74   controlled by t
16790 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54  he.** [SQLITE_ST
167a0 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f  MTJRNL_SPILL] co
167b0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
167c0 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  n..** </dl>.*/.#
167d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
167e0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
167f0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
16800 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16810 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
16820 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
16830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16840 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
16850 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
16860 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16870 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
16880 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
16890 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
168a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
168b0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
168c0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
168d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
168e0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
168f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16900 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
16910 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16920 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16940 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
16950 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16960 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16980 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
16990 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
169a0 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
169b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
169c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
169d0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
169e0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
169f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16a00 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
16a10 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16a20 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16a30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a40 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
16a50 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
16a60 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
16a70 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
16a80 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
16a90 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
16aa0 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
16ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16ac0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16ad0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
16ae0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
16af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16b00 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
16b10 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
16b20 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16b30 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20  ETPCACHE    15  
16b40 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
16b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16b60 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31  G_LOG          1
16b70 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69  6  /* xFunc, voi
16b80 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d* */.#define SQ
16b90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20  LITE_CONFIG_URI 
16ba0 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20           17  /* 
16bb0 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16bc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16bd0 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a  CHE2      18  /*
16be0 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16bf0 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16c00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c10 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20  IG_GETPCACHE2   
16c20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  19  /* sqlite3_p
16c30 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16c50 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
16c60 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20  G_INDEX_SCAN 20 
16c70 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
16c80 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16c90 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31  _SQLLOG       21
16ca0 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f    /* xSqllog, vo
16cb0 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
16cd0 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a  P_SIZE    22  /*
16ce0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20   sqlite3_int64, 
16cf0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f  sqlite3_int64 */
16d00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16d10 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
16d20 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f  PSIZE      23  /
16d30 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23  * int nByte */.#
16d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16d50 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16d60 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20  Z        24  /* 
16d70 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66  int *psz */.#def
16d80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16d90 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20  G_PMASZ         
16da0 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73        25  /* uns
16db0 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20  igned int szPma 
16dc0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16dd0 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e  E_CONFIG_STMTJRN
16de0 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20  L_SPILL      26 
16df0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16e00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16e10 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
16e20 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
16e30 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
16e40 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
16e50 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
16e60 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
16e70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16e80 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
16e90 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
16ea0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16eb0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
16ec0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
16ed0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
16ee0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16ef0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
16f00 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
16f10 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
16f20 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
16f30 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16f40 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
16f50 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
16f60 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
16f70 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
16f80 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
16f90 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16fa0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
16fb0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
16fc0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
16fd0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
16fe0 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
16ff0 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
17000 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
17010 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
17020 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
17030 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
17040 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
17050 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
17060 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
17070 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
17080 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
17090 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
170a0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
170b0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
170c0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
170d0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
170e0 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
170f0 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
17100 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
17110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17120 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
17130 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
17140 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
17150 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
17160 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
17170 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
17180 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
17190 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
171a0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
171b0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
171c0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
171d0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
171e0 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
171f0 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
17200 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
17210 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
17220 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
17230 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
17240 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
17250 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
17260 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
17270 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
17280 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17290 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
172a0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
172b0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
172c0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
172d0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
172e0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
172f0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
17300 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
17310 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
17320 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
17330 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
17340 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
17350 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
17360 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
17370 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
17380 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
17390 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
173a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
173b0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
173c0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
173d0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
173e0 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
173f0 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
17400 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
17410 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
17420 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
17430 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
17440 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
17450 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
17460 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
17470 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
17480 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
17490 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
174a0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
174b0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
174c0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
174d0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
174e0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
174f0 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
17500 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17510 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
17520 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
17530 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
17540 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
17550 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
17560 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
17570 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
17580 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
17590 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
175a0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
175b0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
175c0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
175d0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
175e0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
175f0 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
17600 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
17610 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
17620 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
17630 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
17640 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
17650 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
17660 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
17670 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
17680 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
17690 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
176a0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
176b0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
176c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
176d0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
176e0 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
176f0 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
17700 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
17710 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
17720 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
17730 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17740 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17750 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17760 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17770 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17780 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
17790 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
177a0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
177b0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
177c0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
177d0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
177e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
177f0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
17800 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
17810 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
17820 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
17830 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17840 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17850 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
17860 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
17870 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
17880 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17890 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
178a0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
178b0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
178c0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
178d0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
178e0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
178f0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17900 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
17910 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
17920 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
17930 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
17940 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
17950 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
17960 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
17970 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
17980 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
17990 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
179a0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
179b0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
179c0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
179d0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
179e0 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
179f0 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
17a00 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17a10 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17a20 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17a30 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17a40 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17a50 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
17a60 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
17a70 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
17a80 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
17a90 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54  CONFIG_ENABLE_FT
17aa0 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74  S3_TOKENIZER</dt
17ab0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17ac0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17ad0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17ae0 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75  ble the two-argu
17af0 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20  ment.** version 
17b00 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b  of the [fts3_tok
17b10 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69  enizer()] functi
17b20 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61 72 74  on which is part
17b30 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33   of the.** [FTS3
17b40 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72  ] full-text sear
17b50 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73  ch engine extens
17b60 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ion..** There sh
17b70 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17b80 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17b90 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
17ba0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
17bb0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
17bc0 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33   to disable fts3
17bd0 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a  _tokenizer() or.
17be0 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17bf0 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e  nable fts3_token
17c00 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69  izer() or negati
17c10 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17c20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61  setting.** uncha
17c30 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nged..** The sec
17c40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
17c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17c60 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
17c70 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
17c80 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
17c90 63 61 74 65 20 77 68 65 74 68 65 72 20 66 74 73  cate whether fts
17ca0 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64  3_tokenizer is d
17cb0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
17cc0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17cd0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17ce0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17cf0 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17d00 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17d10 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
17d20 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
17d30 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
17d40 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
17d50 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17d60 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e  NABLE_LOAD_EXTEN
17d70 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SION</dt>.** <dd
17d80 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
17d90 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
17da0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
17db0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
17dc0 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e  tension()].** in
17dd0 74 65 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64  terface independ
17de0 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f  ently of the [lo
17df0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
17e00 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  SQL function..**
17e10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e   The [sqlite3_en
17e20 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  able_load_extens
17e30 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c  ion()] API enabl
17e40 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62  es or disables b
17e50 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49  oth the.** C-API
17e60 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65   [sqlite3_load_e
17e70 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20  xtension()] and 
17e80 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
17e90 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
17ea0 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  ()]..** There sh
17eb0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
17ec0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17ed0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69  ..** When the fi
17ee0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
17ef0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
17f00 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74  s 1, then only t
17f10 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65  he C-API is.** e
17f20 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53  nabled and the S
17f30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61  QL function rema
17f40 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49  ins disabled.  I
17f50 66 20 74 68 65 20 66 69 72 73 74 20 61 72 67 6d  f the first argm
17f60 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69  ent to.** this i
17f70 6e 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74  nterface is 0, t
17f80 68 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41  hen both the C-A
17f90 50 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66  PI and the SQL f
17fa0 75 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61  unction are disa
17fb0 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20  bled..** If the 
17fc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
17fd0 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68  s -1, then no ch
17fe0 61 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74  anges are made t
17ff0 6f 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65  o state of eithe
18000 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f  r the.** C-API o
18010 72 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  r the SQL functi
18020 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  on..** The secon
18030 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18040 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18050 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18060 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18070 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18080 74 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69  te whether [sqli
18090 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
180a0 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  on()] interface.
180b0 2a 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f  ** is disabled o
180c0 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77  r enabled follow
180d0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
180e0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
180f0 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61  eter may.** be a
18100 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
18110 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  n which case the
18120 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
18130 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
18140 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  k..** </dd>.**.*
18150 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
18160 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18170 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
18180 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
18190 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
181a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
181b0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
181c0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
181d0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
181e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
181f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18200 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18210 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18220 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18230 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18240 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18250 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18260 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18270 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18280 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18290 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
182a0 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
182b0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
182c0 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
182d0 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
182e0 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  des.** METHOD: s
182f0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
18300 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
18310 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
18320 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
18330 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
18340 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
18350 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
18360 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
18370 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
18380 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
18390 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
183a0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
183b0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
183c0 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
183d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
183e0 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
183f0 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
18400 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18410 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
18420 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
18430 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
18440 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
18450 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
18460 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
18470 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
18480 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
18490 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
184a0 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
184b0 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
184c0 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
184d0 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
184e0 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
184f0 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
18500 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
18510 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
18520 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
18530 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
18540 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
18550 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
18560 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
18570 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
18580 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
18590 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
185a0 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
185b0 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
185c0 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
185d0 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
185e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
185f0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18600 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
18610 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
18620 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
18630 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
18640 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
18650 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
18660 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
18670 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
18680 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18690 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
186a0 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
186b0 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
186c0 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
186d0 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
186e0 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
186f0 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
18700 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
18710 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
18720 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
18730 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
18740 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18750 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
18760 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
18770 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
18780 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
18790 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
187a0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
187b0 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
187c0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
187d0 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
187e0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
187f0 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
18800 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
18810 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
18820 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
18830 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
18840 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
18850 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18860 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
18870 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18880 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
18890 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
188a0 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
188b0 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
188c0 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
188d0 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
188e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
188f0 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
18900 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
18910 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
18920 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
18930 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
18940 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
18950 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
18960 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
18970 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
18980 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
18990 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
189a0 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
189b0 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
189c0 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
189d0 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
189e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
189f0 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
18a00 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
18a10 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
18a20 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
18a30 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
18a40 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
18a50 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
18a60 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
18a70 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
18a80 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
18a90 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
18aa0 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
18ab0 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
18ac0 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
18ad0 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
18ae0 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
18af0 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
18b00 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
18b10 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
18b20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
18b30 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
18b40 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
18b50 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
18b60 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
18b70 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
18b80 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
18b90 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
18ba0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
18bb0 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
18bc0 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
18bd0 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
18be0 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
18bf0 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
18c00 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18c10 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18c20 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
18c30 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
18c40 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
18c50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
18c60 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
18c70 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18c80 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
18c90 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
18ca0 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
18cb0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
18cc0 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
18cd0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18ce0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
18cf0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
18d00 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
18d10 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
18d20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
18d30 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
18d40 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
18d50 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73  rt [rowid]..*/.s
18d60 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
18d70 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
18d80 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
18d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18da0 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
18db0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
18dc0 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  fied.** METHOD: 
18dd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
18de0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
18df0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
18e00 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64  of rows modified
18e10 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a  , inserted or.**
18e20 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20   deleted by the 
18e30 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
18e40 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
18e50 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
18e60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e  .** statement on
18e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18e80 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69  nnection specifi
18e90 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70  ed by the only p
18ea0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78  arameter..** ^Ex
18eb0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
18ec0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
18ed0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
18ee0 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75   modify the valu
18ef0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
18f00 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a   this function..
18f10 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e  **.** ^Only chan
18f20 67 65 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c  ges made directl
18f30 79 20 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c  y by the INSERT,
18f40 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18f50 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a  E statement are.
18f60 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20  ** considered - 
18f70 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  auxiliary change
18f80 73 20 63 61 75 73 65 64 20 62 79 20 5b 43 52 45  s caused by [CRE
18f90 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
18fa0 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f  iggers], .** [fo
18fb0 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
18fc0 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20  s] or [REPLACE] 
18fd0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
18fe0 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f  ution are not co
18ff0 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68  unted..** .** Ch
19000 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
19010 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
19020 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53  pted by .** [INS
19030 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
19040 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69  | INSTEAD OF tri
19050 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63  ggers] are not c
19060 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c  ounted. ^The val
19070 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ue .** returned 
19080 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
19090 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79  es() immediately
190a0 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54   after an INSERT
190b0 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20  , UPDATE or .** 
190c0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
190d0 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69   run on a view i
190e0 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f  s always zero. O
190f0 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65  nly changes made
19100 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62   to real .** tab
19110 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  les are counted.
19120 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72  .**.** Things ar
19130 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74  e more complicat
19140 65 64 20 69 66 20 74 68 65 20 73 71 6c 69 74 65  ed if the sqlite
19150 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
19160 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75  tion is.** execu
19170 74 65 64 20 77 68 69 6c 65 20 61 20 74 72 69 67  ted while a trig
19180 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72  ger program is r
19190 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79  unning. This may
191a0 20 68 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a   happen if the.*
191b0 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74  * program uses t
191c0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
191d0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20  L function], or 
191e0 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61  if some other ca
191f0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
19200 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74  on invokes sqlit
19210 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72  e3_changes() dir
19220 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c  ectly. Essential
19230 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a  ly:.** .** <ul>.
19240 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f  **   <li> ^(Befo
19250 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72  re entering a tr
19260 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68  igger program th
19270 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
19280 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71   by.**        sq
19290 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
192a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65  function is save
192b0 64 2e 20 41 66 74 65 72 20 74 68 65 20 74 72 69  d. After the tri
192c0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a  gger program .**
192d0 20 20 20 20 20 20 20 20 68 61 73 20 66 69 6e 69          has fini
192e0 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e  shed, the origin
192f0 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65 73 74  al value is rest
19300 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20  ored.)^.** .**  
19310 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61   <li> ^(Within a
19320 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
19330 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50   each INSERT, UP
19340 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20  DATE and DELETE 
19350 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61 74 65  .**        state
19360 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20 76 61  ment sets the va
19370 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19380 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19390 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f  ) .**        upo
193a0 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20  n completion as 
193b0 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73  normal. Of cours
193c0 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20 77 69  e, this value wi
193d0 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a  ll not include .
193e0 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20 63 68  **        any ch
193f0 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20  anges performed 
19400 62 79 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c  by sub-triggers,
19410 20 61 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f   as the sqlite3_
19420 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20  changes() .**   
19430 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20       value will 
19440 62 65 20 73 61 76 65 64 20 61 6e 64 20 72 65 73  be saved and res
19450 74 6f 72 65 64 20 61 66 74 65 72 20 65 61 63 68  tored after each
19460 20 73 75 62 2d 74 72 69 67 67 65 72 20 68 61 73   sub-trigger has
19470 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e   run.)^.** </ul>
19480 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65  .** .** ^This me
19490 61 6e 73 20 74 68 61 74 20 69 66 20 74 68 65 20  ans that if the 
194a0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
194b0 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c  nction (or simil
194c0 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62  ar) is used.** b
194d0 79 20 74 68 65 20 66 69 72 73 74 20 49 4e 53 45  y the first INSE
194e0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
194f0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
19500 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c  ithin a trigger,
19510 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20   it .** returns 
19520 74 68 65 20 76 61 6c 75 65 20 61 73 20 73 65 74  the value as set
19530 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e   when the callin
19540 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61  g statement bega
19550 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  n executing..** 
19560 5e 49 66 20 69 74 20 69 73 20 75 73 65 64 20 62  ^If it is used b
19570 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20  y the second or 
19580 73 75 62 73 65 71 75 65 6e 74 20 73 75 63 68 20  subsequent such 
19590 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
195a0 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70   a trigger .** p
195b0 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75  rogram, the valu
195c0 65 20 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65  e returned refle
195d0 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  cts the number o
195e0 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20  f rows modified 
195f0 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69  by the .** previ
19600 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ous INSERT, UPDA
19610 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
19620 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
19630 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a  e same trigger..
19640 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
19650 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
19660 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
19670 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
19680 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
19690 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
196a0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
196b0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
196c0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
196d0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
196e0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
196f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19700 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
19710 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
19720 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
19730 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19740 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
19750 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
19760 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
19770 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
19780 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19790 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
197a0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
197b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
197c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
197d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
197e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
197f0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
19800 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
19810 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
19820 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
19830 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
19840 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
19850 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
19860 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
19870 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19880 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
19890 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
198a0 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
198b0 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
198c0 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
198d0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
198e0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
198f0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
19900 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
19910 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
19920 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
19930 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
19940 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
19950 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
19960 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
19970 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
19980 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
19990 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
199a0 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
199b0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
199c0 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
199d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
199e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
199f0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
19a00 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
19a10 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
19a20 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
19a30 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
19a40 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
19a50 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
19a60 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
19a70 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
19a80 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19a90 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19aa0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19ab0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
19ac0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
19ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19ae0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
19af0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
19b00 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
19b10 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
19b20 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
19b30 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
19b40 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
19b50 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
19b60 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
19b70 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19b80 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
19b90 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
19ba0 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
19bb0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19bc0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
19bd0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
19be0 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
19bf0 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
19c00 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
19c10 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
19c20 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
19c30 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
19c40 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
19c50 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
19c60 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
19c70 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
19c80 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
19c90 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
19ca0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
19cb0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
19cc0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
19cd0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
19ce0 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
19cf0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
19d00 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
19d10 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
19d20 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
19d30 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
19d40 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
19d50 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
19d60 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
19d70 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
19d80 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
19d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19da0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
19db0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
19dc0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
19dd0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
19de0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
19df0 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
19e00 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
19e10 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
19e20 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
19e30 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19e40 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
19e50 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
19e60 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
19e70 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
19e80 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
19e90 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
19ea0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
19eb0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
19ec0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
19ed0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
19ee0 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
19ef0 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
19f00 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
19f10 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
19f20 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
19f30 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
19f40 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
19f50 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
19f60 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
19f70 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
19f80 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
19f90 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
19fa0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
19fb0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
19fc0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
19fd0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
19fe0 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
19ff0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1a000 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1a010 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a020 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1a030 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1a040 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1a050 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1a060 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1a070 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1a080 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1a090 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1a0a0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1a0b0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1a0c0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1a0d0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1a0e0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1a0f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a100 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1a110 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1a120 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1a130 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1a140 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1a150 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1a160 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1a170 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1a180 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1a190 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1a1a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1a1b0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1a1c0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1a1d0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1a1e0 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1a1f0 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1a200 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1a210 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a220 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a230 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1a240 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1a250 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
1a260 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1a270 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1a280 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a290 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
1a2a0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1a2b0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
1a2c0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
1a2d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
1a2e0 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1a2f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a300 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1a310 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1a320 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1a330 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a340 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1a350 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1a360 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1a370 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1a380 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1a390 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1a3a0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1a3b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1a3c0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1a3d0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1a3e0 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1a3f0 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1a400 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1a410 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1a420 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1a430 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1a440 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1a450 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1a460 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1a470 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1a480 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1a490 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1a4a0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1a4b0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1a4c0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1a4d0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1a4e0 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1a4f0 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1a500 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1a510 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1a520 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1a530 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1a540 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1a550 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1a560 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1a570 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1a580 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1a590 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1a5a0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1a5b0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1a5c0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1a5d0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1a5e0 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1a5f0 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1a600 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1a610 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1a620 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1a630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1a640 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1a650 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1a660 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1a670 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1a680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1a690 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1a6a0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1a6b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1a6c0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1a6d0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1a6e0 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1a6f0 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1a700 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1a710 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1a720 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1a730 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1a740 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1a750 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1a760 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1a770 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1a780 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1a790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1a7a0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1a7b0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1a7c0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1a7d0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1a7e0 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1a7f0 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1a800 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1a810 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1a820 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1a830 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1a840 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1a850 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1a860 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1a870 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1a880 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1a890 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1a8a0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1a8b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1a8c0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1a8d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1a8e0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1a8f0 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1a900 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1a910 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1a920 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1a930 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1a940 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1a950 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
1a960 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
1a970 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1a980 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1a990 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a9a0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1a9b0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1a9c0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1a9d0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1a9e0 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1a9f0 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1aa00 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1aa10 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1aa20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1aa30 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1aa40 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1aa50 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1aa60 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1aa70 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1aa80 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1aa90 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1aaa0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1aab0 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1aac0 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1aad0 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1aae0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1aaf0 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1ab00 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1ab10 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1ab20 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1ab30 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ab40 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1ab50 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1ab60 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1ab70 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1ab80 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1ab90 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1aba0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1abb0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1abc0 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1abd0 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1abe0 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1abf0 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1ac00 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1ac10 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1ac20 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1ac30 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1ac40 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1ac50 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1ac60 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1ac70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1ac80 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1ac90 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1aca0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1acb0 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1acc0 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1acd0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1ace0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1acf0 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1ad00 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1ad10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1ad20 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1ad30 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1ad40 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1ad50 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1ad60 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1ad70 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1ad80 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1ad90 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1ada0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1adb0 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1adc0 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1add0 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1ade0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1adf0 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1ae00 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1ae10 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1ae20 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1ae30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1ae40 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1ae50 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1ae60 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1ae70 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1ae80 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1ae90 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1aea0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1aeb0 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1aec0 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1aed0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1aee0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1aef0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1af00 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1af10 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1af20 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1af30 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1af40 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1af50 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1af60 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1af70 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1af80 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1af90 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1afa0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1afb0 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1afc0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1afd0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1afe0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1aff0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1b000 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1b010 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1b020 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1b030 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1b040 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1b050 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b060 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1b070 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1b080 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1b090 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1b0a0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1b0b0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1b0c0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1b0d0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1b0e0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1b0f0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1b100 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1b110 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1b120 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1b130 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1b140 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1b150 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1b160 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1b170 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1b180 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1b190 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1b1a0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1b1b0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1b1c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1b1d0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1b1e0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1b1f0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1b200 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1b210 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1b220 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1b230 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1b240 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1b250 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1b260 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1b270 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1b280 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1b290 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1b2a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1b2b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1b2c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1b2d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1b2e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1b2f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1b300 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1b310 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1b320 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1b330 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1b340 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1b350 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1b360 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1b370 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1b380 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1b390 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1b3a0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1b3b0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1b3c0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1b3d0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1b3e0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1b3f0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1b400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b410 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1b420 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1b430 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1b440 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1b450 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1b460 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1b470 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1b480 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1b490 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1b4a0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1b4b0 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1b4c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b4d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1b4e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1b4f0 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1b500 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1b510 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
1b520 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1b530 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1b540 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1b550 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b560 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1b570 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1b580 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b590 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1b5a0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1b5b0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1b5c0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1b5d0 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1b5e0 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1b5f0 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1b600 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1b610 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1b620 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1b630 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1b640 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1b650 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1b660 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1b670 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1b680 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1b690 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1b6a0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1b6b0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1b6c0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1b6d0 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1b6e0 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1b6f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1b700 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1b710 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b720 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1b730 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1b740 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1b750 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1b760 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1b770 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1b780 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1b790 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1b7a0 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1b7b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b7c0 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1b7d0 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1b7e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1b7f0 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1b800 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1b810 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1b820 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1b830 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1b840 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1b850 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1b860 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1b870 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1b880 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1b890 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1b8a0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1b8b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1b8c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b8d0 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1b8e0 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1b8f0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1b900 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1b910 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1b920 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1b930 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1b940 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1b950 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1b960 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1b970 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1b980 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1b990 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1b9a0 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1b9b0 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1b9c0 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1b9d0 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1b9e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b9f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1ba00 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1ba10 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1ba20 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1ba30 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1ba40 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1ba50 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1ba60 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1ba70 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1ba80 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1ba90 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1baa0 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1bab0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1bac0 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1bad0 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1bae0 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1baf0 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1bb00 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1bb10 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1bb20 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1bb30 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1bb40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1bb50 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1bb60 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1bb70 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1bb80 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1bb90 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1bba0 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1bbb0 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1bbc0 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1bbd0 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1bbe0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1bbf0 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1bc00 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1bc10 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1bc20 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1bc30 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1bc40 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1bc50 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1bc60 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1bc70 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1bc80 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1bc90 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1bca0 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1bcb0 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1bcc0 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1bcd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1bce0 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1bcf0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1bd00 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1bd10 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1bd20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1bd30 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1bd40 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1bd50 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1bd60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1bd70 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1bd80 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1bd90 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1bda0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1bdb0 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1bdc0 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1bdd0 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1bde0 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1bdf0 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1be00 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1be10 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1be20 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1be30 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1be40 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1be50 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1be60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1be70 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1be80 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1be90 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1bea0 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1beb0 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1bec0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1bed0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1bee0 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1bef0 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1bf00 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1bf10 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1bf20 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1bf30 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1bf40 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1bf50 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1bf60 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1bf70 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1bf80 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1bf90 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1bfa0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1bfb0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1bfc0 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1bfd0 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1bfe0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1bff0 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1c000 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c010 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1c020 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c030 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1c040 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c050 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1c060 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1c070 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1c080 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1c090 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1c0a0 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1c0b0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1c0c0 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1c0d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c0e0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1c0f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1c100 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1c110 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1c120 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1c130 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1c140 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1c150 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1c160 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1c170 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1c180 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1c190 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1c1a0 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1c1b0 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1c1c0 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1c1d0 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1c1e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1c1f0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1c200 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1c210 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c220 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1c230 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1c240 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1c250 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1c260 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1c270 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1c280 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1c290 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1c2a0 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1c2b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1c2c0 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1c2d0 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1c2e0 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1c2f0 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1c300 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1c310 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1c320 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1c330 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1c340 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1c350 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1c360 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1c370 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1c380 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1c390 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1c3a0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1c3b0 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1c3c0 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1c3d0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1c3e0 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1c3f0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1c400 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1c410 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1c420 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1c430 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1c440 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1c450 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1c460 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1c470 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1c480 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1c490 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1c4a0 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1c4b0 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1c4c0 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1c4d0 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1c4e0 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1c4f0 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1c500 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1c510 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1c520 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1c530 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1c540 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1c550 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1c560 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1c570 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1c580 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1c590 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1c5a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1c5b0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1c5c0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1c5d0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1c5e0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1c5f0 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1c600 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1c610 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1c620 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1c630 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1c640 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1c650 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1c660 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1c670 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1c680 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1c690 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1c6a0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1c6b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1c6c0 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1c6d0 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1c6e0 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1c6f0 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1c700 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1c710 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1c720 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1c730 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1c740 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1c750 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1c760 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1c770 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1c780 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1c790 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1c7a0 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1c7b0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1c7c0 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1c7d0 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1c7e0 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1c7f0 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1c800 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1c810 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1c820 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1c830 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1c840 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1c850 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1c860 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1c870 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1c880 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c890 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1c8a0 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1c8b0 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1c8c0 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1c8d0 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1c8e0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1c8f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1c900 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1c910 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1c920 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1c930 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1c940 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1c950 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1c960 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c970 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1c980 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1c990 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1c9a0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1c9b0 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1c9c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1c9d0 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1c9e0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1c9f0 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1ca00 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1ca10 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1ca20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1ca30 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1ca40 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1ca50 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1ca60 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1ca70 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1ca80 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1ca90 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1caa0 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1cab0 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1cac0 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1cad0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1cae0 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1caf0 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1cb00 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1cb10 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1cb20 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1cb30 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1cb40 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1cb50 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1cb60 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1cb70 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1cb80 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1cb90 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1cba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1cbb0 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1cbc0 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1cbd0 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1cbe0 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1cbf0 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1cc00 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1cc10 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1cc20 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1cc30 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1cc40 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1cc50 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1cc60 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1cc70 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1cc80 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1cc90 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1cca0 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1ccb0 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1ccc0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1ccd0 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1cce0 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1ccf0 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1cd00 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1cd10 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1cd20 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1cd30 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1cd40 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1cd50 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1cd60 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1cd70 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1cd80 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1cd90 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1cda0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1cdb0 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1cdc0 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1cdd0 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1cde0 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1cdf0 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1ce00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ce10 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1ce20 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1ce30 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1ce40 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1ce50 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1ce60 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1ce70 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1ce80 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1ce90 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1cea0 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1ceb0 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1cec0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1ced0 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1cee0 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1cef0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1cf00 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1cf10 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1cf20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1cf30 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1cf40 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1cf50 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1cf60 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1cf70 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1cf80 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1cf90 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1cfa0 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1cfb0 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1cfc0 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1cfd0 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1cfe0 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1cff0 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1d000 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1d010 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1d020 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1d030 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1d040 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1d050 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1d060 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1d070 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1d080 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1d090 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1d0a0 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1d0b0 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1d0c0 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1d0d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1d0e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1d0f0 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1d100 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1d110 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d120 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1d130 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1d140 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1d150 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1d160 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1d170 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1d180 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1d190 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1d1a0 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1d1b0 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1d1c0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1d1d0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1d1e0 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1d1f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1d200 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1d210 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1d220 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1d230 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1d240 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1d250 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1d260 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1d270 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1d280 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1d290 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1d2a0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1d2b0 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1d2c0 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1d2d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1d2e0 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1d2f0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1d300 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1d310 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1d320 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1d330 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1d340 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1d350 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1d360 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1d370 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1d380 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1d390 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1d3a0 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1d3b0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1d3c0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1d3d0 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1d3e0 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1d3f0 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1d400 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1d410 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1d420 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1d430 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1d440 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1d450 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1d460 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1d470 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1d480 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1d490 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1d4a0 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1d4b0 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1d4c0 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1d4d0 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1d4e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1d4f0 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1d500 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1d510 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1d520 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1d530 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1d540 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1d550 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1d560 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1d570 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1d580 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1d590 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1d5a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d5b0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1d5c0 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1d5d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1d5e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1d5f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1d600 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1d610 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1d620 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1d630 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1d640 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1d650 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1d660 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1d670 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1d680 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1d690 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1d6a0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1d6b0 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1d6c0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1d6d0 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1d6e0 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1d6f0 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1d700 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1d710 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1d720 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1d730 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1d740 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1d750 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1d760 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1d770 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1d780 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1d790 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1d7a0 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1d7b0 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1d7c0 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1d7d0 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1d7e0 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1d7f0 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1d800 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1d810 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1d820 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1d830 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1d840 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1d850 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1d860 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1d870 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1d880 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1d890 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1d8a0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1d8b0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1d8c0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1d8d0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1d8e0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1d8f0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1d900 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1d910 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1d920 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1d930 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1d940 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1d950 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1d960 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1d970 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1d980 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1d990 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1d9a0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1d9b0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1d9c0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1d9d0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1d9e0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1d9f0 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1da00 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1da10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1da20 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1da30 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1da40 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1da50 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1da60 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1da70 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1da80 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1da90 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1daa0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1dab0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1dac0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1dad0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1dae0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1daf0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1db00 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1db10 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1db20 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1db30 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1db40 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1db50 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1db60 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1db70 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1db80 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1db90 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1dba0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1dbb0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1dbc0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1dbd0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1dbe0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1dbf0 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1dc00 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1dc10 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1dc20 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1dc30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1dc40 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1dc50 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1dc60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1dc70 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1dc80 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1dc90 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1dca0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1dcb0 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1dcc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1dcd0 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1dce0 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1dcf0 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1dd00 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1dd10 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1dd20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dd30 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1dd40 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1dd50 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1dd60 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1dd70 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1dd80 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1dd90 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1dda0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1ddb0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1ddc0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1ddd0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1dde0 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1ddf0 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1de00 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1de10 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1de20 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1de30 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1de40 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1de50 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1de60 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1de70 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1de80 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1de90 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1dea0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1deb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1dec0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ded0 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1dee0 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1def0 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1df00 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1df10 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1df20 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1df30 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1df40 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1df50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1df60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1df70 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1df80 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1df90 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1dfa0 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1dfb0 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1dfc0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1dfd0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1dfe0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1dff0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e000 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1e010 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1e020 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1e030 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1e040 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e050 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1e060 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1e070 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e080 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1e090 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1e0a0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1e0b0 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1e0c0 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1e0d0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1e0e0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1e0f0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1e100 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1e110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e120 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1e130 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1e140 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1e150 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1e160 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1e170 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1e180 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1e190 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1e1a0 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1e1b0 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1e1c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1e1d0 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1e1e0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1e1f0 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1e200 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1e210 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1e220 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1e230 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1e240 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1e250 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1e260 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1e270 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1e280 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1e290 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1e2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e2b0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1e2c0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1e2d0 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1e2e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1e2f0 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1e300 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1e310 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1e320 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1e330 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1e340 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1e350 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1e360 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1e370 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1e380 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e390 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1e3a0 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1e3b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e3c0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1e3d0 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1e3e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1e3f0 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1e400 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1e410 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1e420 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1e430 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1e440 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1e450 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1e460 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1e470 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1e480 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1e490 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1e4a0 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1e4b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1e4c0 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1e4d0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1e4e0 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1e4f0 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1e500 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1e510 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1e520 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1e530 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1e540 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1e550 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1e560 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1e570 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1e580 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1e590 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1e5a0 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1e5b0 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1e5c0 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1e5d0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1e5e0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1e5f0 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1e600 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1e610 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1e620 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1e630 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1e640 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1e650 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1e660 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1e670 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1e680 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1e690 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1e6a0 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1e6b0 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1e6c0 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1e6d0 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1e6e0 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1e6f0 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1e700 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1e710 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1e720 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1e730 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1e740 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1e750 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1e760 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1e770 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1e780 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1e790 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1e7a0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1e7b0 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1e7c0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1e7d0 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1e7e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1e7f0 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1e800 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1e810 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1e820 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1e830 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1e840 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1e850 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1e860 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1e870 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1e880 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1e890 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1e8a0 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1e8b0 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1e8c0 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1e8d0 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1e8e0 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1e8f0 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1e900 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1e910 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1e920 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1e930 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1e940 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1e950 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1e960 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1e970 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1e980 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1e990 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1e9a0 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1e9b0 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1e9c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1e9d0 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1e9e0 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1e9f0 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1ea00 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1ea10 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1ea20 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1ea30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1ea40 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1ea50 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1ea60 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1ea70 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1ea80 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1ea90 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1eaa0 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1eab0 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1eac0 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1ead0 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1eae0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1eaf0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1eb00 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1eb10 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1eb20 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1eb30 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1eb40 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1eb50 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1eb60 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1eb70 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1eb80 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1eb90 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1eba0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1ebb0 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1ebc0 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1ebd0 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1ebe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ebf0 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1ec00 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1ec10 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1ec20 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1ec30 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1ec40 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1ec50 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1ec60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1ec70 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1ec80 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1ec90 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1eca0 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1ecb0 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1ecc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ecd0 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1ece0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1ecf0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1ed00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1ed10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1ed20 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1ed30 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1ed40 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1ed50 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1ed60 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1ed70 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1ed80 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1ed90 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1eda0 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1edb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1edc0 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1edd0 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1ede0 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1edf0 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1ee00 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1ee10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ee20 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1ee30 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ee40 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1ee50 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1ee60 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1ee70 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1ee80 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1ee90 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1eea0 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1eeb0 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1eec0 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1eed0 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1eee0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1eef0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1ef00 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1ef10 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1ef20 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1ef30 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1ef40 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1ef50 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ef60 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1ef70 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1ef80 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1ef90 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1efa0 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1efb0 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1efc0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1efd0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1efe0 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1eff0 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1f000 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1f010 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1f020 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1f030 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1f040 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1f050 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f060 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1f070 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1f080 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1f090 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1f0a0 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1f0b0 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1f0c0 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1f0d0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1f0e0 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1f0f0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1f100 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1f110 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1f120 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1f130 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1f140 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1f150 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1f160 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1f170 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1f180 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1f190 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1f1a0 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1f1b0 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1f1c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1f1d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1f1e0 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1f1f0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1f200 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1f210 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1f220 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1f230 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1f240 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1f250 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1f260 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1f270 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1f280 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1f290 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1f2a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1f2b0 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1f2c0 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1f2d0 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1f2e0 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1f2f0 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1f300 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1f310 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1f320 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1f330 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1f340 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1f350 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1f360 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1f370 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1f380 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1f390 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1f3a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1f3b0 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1f3c0 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1f3d0 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1f3e0 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1f3f0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1f400 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1f410 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1f420 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1f430 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1f440 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1f450 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1f460 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1f470 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1f480 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1f490 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1f4a0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1f4b0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
1f4c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1f4d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1f4e0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1f4f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1f500 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1f510 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1f520 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1f530 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1f540 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1f550 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1f560 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1f570 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1f580 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1f590 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1f5a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f5b0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1f5c0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1f5d0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1f5e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1f5f0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1f600 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1f610 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1f620 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1f630 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1f640 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1f650 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1f660 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1f670 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1f680 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1f690 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1f6a0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1f6b0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1f6c0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1f6d0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1f6e0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1f6f0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1f700 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1f710 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1f720 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1f730 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1f740 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1f750 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1f760 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1f770 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1f780 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1f790 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1f7a0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1f7b0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1f7c0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1f7d0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1f7e0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f7f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1f800 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1f810 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1f820 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1f830 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1f840 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1f850 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1f860 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1f870 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1f880 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1f890 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1f8a0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1f8b0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1f8c0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1f8d0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1f8e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1f8f0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1f900 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1f910 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1f920 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1f930 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1f940 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1f950 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f960 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1f970 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1f980 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1f990 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1f9a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1f9b0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1f9c0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1f9d0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1f9e0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1f9f0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1fa00 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fa10 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1fa20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1fa30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1fa40 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fa50 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1fa60 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1fa70 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1fa80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fa90 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1faa0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1fab0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1fac0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1fad0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1fae0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1faf0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1fb00 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1fb10 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1fb20 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1fb30 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1fb40 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1fb50 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1fb60 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1fb70 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1fb80 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1fb90 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1fba0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1fbb0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1fbc0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1fbd0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1fbe0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1fbf0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1fc00 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1fc10 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1fc20 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1fc30 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1fc40 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1fc50 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1fc60 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1fc70 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1fc80 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1fc90 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1fca0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1fcb0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1fcc0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1fcd0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1fce0 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1fcf0 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1fd00 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1fd10 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1fd20 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1fd30 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1fd40 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1fd50 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1fd60 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1fd70 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1fd80 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1fd90 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1fda0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1fdb0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1fdc0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1fdd0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1fde0 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1fdf0 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1fe00 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1fe10 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1fe20 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1fe30 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1fe40 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1fe50 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1fe60 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1fe70 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1fe80 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1fe90 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1fea0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1feb0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1fec0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1fed0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1fee0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1fef0 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1ff00 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1ff10 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1ff20 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1ff30 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1ff40 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1ff50 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1ff60 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1ff70 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1ff80 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1ff90 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1ffa0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1ffb0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1ffc0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1ffd0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1ffe0 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1fff0 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
20000 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
20010 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
20020 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
20030 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
20040 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
20050 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
20060 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
20070 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
20080 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
20090 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
200a0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
200b0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
200c0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
200d0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
200e0 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
200f0 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
20100 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
20110 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
20120 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
20130 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
20140 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
20150 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
20160 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
20170 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20180 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
20190 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
201a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
201b0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
201c0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
201d0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
201e0 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
201f0 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
20200 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
20210 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
20220 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
20230 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
20240 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
20250 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
20260 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
20270 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20280 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20290 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
202a0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
202b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
202c0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
202d0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
202e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
202f0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20300 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20310 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20320 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20330 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20340 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20350 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20360 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20370 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20380 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
20390 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
203a0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
203b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
203c0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
203d0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
203e0 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
203f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
20400 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
20410 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
20420 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
20430 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
20440 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
20450 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
20460 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
20470 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20480 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
20490 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
204a0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
204b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
204c0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
204d0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
204e0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
204f0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
20500 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
20510 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20520 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20530 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20540 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20550 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20560 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20570 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20580 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20590 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
205a0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
205b0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
205c0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
205d0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
205e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
205f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
20600 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
20610 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
20620 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
20630 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
20640 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20650 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
20660 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
20670 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20680 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
20690 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
206a0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
206b0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
206c0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
206d0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
206e0 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
206f0 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
20700 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
20710 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
20720 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
20730 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
20740 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
20750 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
20760 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20770 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
20780 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
20790 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
207a0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
207b0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
207c0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
207d0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
207e0 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
207f0 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
20800 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
20810 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
20820 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
20830 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
20840 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
20850 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
20860 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
20870 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
20880 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
20890 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
208a0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
208b0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
208c0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
208d0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
208e0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
208f0 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
20900 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
20910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20920 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
20930 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
20940 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20950 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
20960 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
20970 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
20980 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
20990 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
209a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
209b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
209c0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
209d0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
209e0 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
209f0 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
20a00 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
20a10 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
20a20 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
20a30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20a40 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
20a50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
20a60 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
20a70 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
20a80 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
20a90 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
20aa0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
20ab0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
20ac0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
20ad0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
20ae0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
20af0 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
20b00 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
20b10 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
20b20 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
20b30 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
20b40 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
20b50 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
20b60 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
20b70 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20b80 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
20b90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
20ba0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
20bb0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
20bc0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
20bd0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20be0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20bf0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
20c00 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
20c10 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
20c20 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
20c30 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
20c40 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
20c50 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
20c60 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
20c70 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
20c80 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
20c90 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
20ca0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
20cb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20cc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
20cd0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
20ce0 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
20cf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20d00 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
20d10 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
20d20 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20d30 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20d40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20d50 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
20d60 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
20d70 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20d80 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20da0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
20db0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
20dc0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20dd0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20de0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20df0 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
20e00 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
20e10 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20e20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20e30 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20e40 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
20e50 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
20e60 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
20e70 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20e80 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20e90 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
20ea0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
20eb0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20ec0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20ed0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20ee0 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
20ef0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20f00 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20f10 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20f20 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
20f30 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
20f40 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20f50 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20f60 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20f70 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
20f80 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
20f90 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20fa0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20fb0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20fc0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
20fd0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
20fe0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20ff0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21000 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21010 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
21020 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
21030 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21040 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21050 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21060 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
21070 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
21080 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
21090 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
210a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
210b0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
210c0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
210d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
210e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
210f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21100 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
21110 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
21120 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21130 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21140 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21150 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
21160 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
21170 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21180 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
211a0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
211b0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
211c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
211d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
211e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
211f0 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
21200 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
21210 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21220 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21230 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
21240 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
21250 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
21260 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21270 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21280 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
21290 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
212a0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
212b0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
212c0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
212d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
212e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
212f0 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
21300 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21310 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21320 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
21330 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21340 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
21350 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
21360 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21370 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
21380 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
21390 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
213a0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
213b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
213c0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
213d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
213e0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
213f0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21400 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21410 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
21420 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
21430 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
21440 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21450 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21460 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
21470 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
21480 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
21490 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
214a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
214b0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
214c0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
214d0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
214e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
214f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21500 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
21510 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
21520 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21530 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21540 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21550 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
21560 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
21570 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21580 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21590 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
215a0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
215b0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
215c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
215d0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
215e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
215f0 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
21600 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
21610 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
21620 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
21630 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21640 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
21650 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
21660 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
21670 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
21680 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21690 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
216a0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
216b0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
216c0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
216d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
216e0 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
216f0 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
21700 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
21710 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
21720 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
21730 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
21740 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
21750 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
21760 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
21770 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
21780 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
21790 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
217a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
217b0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
217c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
217d0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
217e0 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
217f0 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
21800 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
21810 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
21820 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21830 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21840 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21850 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
21860 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
21870 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
21880 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
21890 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
218a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
218b0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
218c0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
218d0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
218e0 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
218f0 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
21900 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
21910 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
21920 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
21930 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
21940 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
21950 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21960 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
21970 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
21980 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
21990 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
219a0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
219b0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
219c0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
219d0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
219e0 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
219f0 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
21a00 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
21a10 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
21a20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
21a30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
21a40 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
21a50 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
21a60 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
21a70 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
21a80 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
21a90 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
21aa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21ab0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
21ac0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
21ad0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
21ae0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
21af0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
21b00 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
21b10 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
21b20 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
21b30 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
21b40 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
21b50 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
21b60 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
21b70 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
21b80 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
21b90 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
21ba0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
21bb0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
21bc0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
21bd0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
21be0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
21bf0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
21c00 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
21c10 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
21c20 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
21c30 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
21c40 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
21c50 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
21c60 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21c70 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
21c80 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
21c90 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
21ca0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
21cb0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
21cc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
21cd0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
21ce0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
21cf0 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
21d00 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
21d10 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
21d20 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
21d30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
21d40 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
21d50 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
21d60 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
21d70 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
21d80 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
21d90 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
21da0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
21db0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
21dc0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
21dd0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
21de0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21df0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
21e00 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
21e10 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ks.** METHOD: sq
21e20 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
21e30 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
21e40 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
21e50 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
21e60 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
21e70 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
21e80 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
21e90 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
21ea0 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
21eb0 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
21ec0 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
21ed0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
21ee0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
21ef0 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
21f00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21f10 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
21f20 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
21f30 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
21f40 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
21f50 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
21f60 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
21f70 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
21f80 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
21f90 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
21fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21fb0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
21fc0 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
21fd0 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
21fe0 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
21ff0 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
22000 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
22010 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
22020 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
22030 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
22040 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
22050 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
22060 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
22070 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
22080 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
22090 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
220a0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
220b0 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
220c0 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
220d0 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
220e0 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
220f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22100 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
22110 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
22120 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
22130 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
22140 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
22150 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
22160 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
22170 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
22180 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
22190 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
221a0 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
221b0 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
221c0 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
221d0 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
221e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
221f0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
22200 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
22210 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
22220 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
22230 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
22240 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
22250 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
22260 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
22270 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
22280 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22290 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
222a0 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
222b0 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
222c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
222d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
222e0 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
222f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
22300 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
22310 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22320 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22330 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
22340 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
22350 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22360 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
22370 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
22380 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
22390 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  .**.*/.void sqli
223a0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
223b0 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
223c0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
223d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
223e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
223f0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
22400 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
22410 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
22420 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
22430 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
22440 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
22450 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
22460 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
22470 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
22480 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
22490 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
224a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
224b0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
224c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
224d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
224e0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
224f0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
22500 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
22510 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
22520 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
22530 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
22540 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
22550 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
22560 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
22570 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
22580 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
22590 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
225a0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
225b0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
225c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
225d0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
225e0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
225f0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
22600 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
22610 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
22620 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
22630 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
22640 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22650 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
22660 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
22670 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
22680 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
22690 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
226a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
226b0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
226c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
226d0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
226e0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
226f0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
22700 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
22710 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
22720 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
22730 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
22740 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
22750 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
22760 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
22770 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
22780 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
22790 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
227a0 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
227b0 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
227c0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
227d0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
227e0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
227f0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
22800 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
22810 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
22820 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
22830 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
22840 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
22850 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
22860 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
22870 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
22880 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
22890 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
228a0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
228b0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
228c0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
228d0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
228e0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
228f0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
22900 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
22910 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
22920 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
22930 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
22940 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
22950 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
22960 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
22970 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
22980 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
22990 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
229a0 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
229b0 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
229c0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
229d0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
229e0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
229f0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
22a00 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
22a10 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
22a20 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
22a30 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
22a40 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
22a50 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
22a60 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
22a70 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
22a80 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
22a90 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
22aa0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
22ab0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
22ac0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
22ad0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
22ae0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
22af0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
22b00 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
22b10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
22b20 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
22b30 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
22b40 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
22b50 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
22b60 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
22b70 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
22b80 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
22b90 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
22ba0 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
22bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
22bc0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
22bd0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
22be0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
22bf0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
22c00 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
22c10 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
22c20 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
22c30 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
22c40 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
22c50 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
22c60 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
22c70 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
22c80 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
22c90 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
22ca0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
22cb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22cc0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
22cd0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
22ce0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
22cf0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
22d00 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
22d10 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
22d20 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
22d30 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
22d40 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
22d50 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
22d60 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
22d70 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
22d80 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
22d90 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
22da0 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
22db0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
22dc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
22dd0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
22de0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
22df0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
22e00 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
22e10 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
22e20 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
22e30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
22e40 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
22e50 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
22e60 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
22e70 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
22e80 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
22e90 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
22ea0 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
22eb0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22ec0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
22ed0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
22ee0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
22ef0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
22f00 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
22f10 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
22f20 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
22f30 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
22f40 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
22f50 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
22f60 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
22f70 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
22f80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22f90 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
22fa0 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
22fb0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
22fc0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
22fd0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
22fe0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
22ff0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
23000 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
23010 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
23020 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
23030 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
23040 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
23050 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
23060 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
23070 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
23080 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
23090 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
230a0 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
230b0 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
230c0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
230d0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
230e0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
230f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23100 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
23110 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
23120 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
23130 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
23140 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
23150 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
23160 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
23170 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
23180 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
23190 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
231a0 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
231b0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
231c0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
231d0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
231e0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
231f0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
23200 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
23210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
23220 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
23230 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
23240 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
23250 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
23260 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
23270 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
23280 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
23290 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
232a0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
232b0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
232c0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
232d0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
232e0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
232f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
23300 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
23310 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
23320 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
23330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23340 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
23350 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
23360 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
23370 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
23380 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
23390 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
233a0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
233b0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
233c0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
233d0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
233e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
233f0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
23400 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
23410 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
23420 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
23430 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
23440 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
23450 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
23460 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
23470 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
23480 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
23490 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
234a0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
234b0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
234c0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
234d0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
234e0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
234f0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
23500 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
23510 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
23520 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23530 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
23540 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
23550 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
23560 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
23570 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
23580 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
23590 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
235a0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
235b0 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
235c0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
235d0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
235e0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
235f0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
23600 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
23610 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
23620 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
23630 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
23640 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
23650 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
23660 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
23670 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
23680 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23690 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
236a0 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
236b0 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
236c0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
236d0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
236e0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
236f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
23700 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
23710 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
23720 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
23730 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
23740 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
23750 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
23760 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
23770 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
23780 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
23790 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
237a0 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
237b0 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
237c0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
237d0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
237e0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
237f0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
23800 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
23810 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
23820 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
23830 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
23840 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
23850 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
23860 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
23870 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
23880 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
23890 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
238a0 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
238b0 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
238c0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
238d0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
238e0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
238f0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
23900 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
23910 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
23920 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
23930 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
23940 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
23950 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
23960 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
23970 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
23980 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
23990 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
239a0 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
239b0 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
239c0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
239d0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
239e0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
239f0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
23a00 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
23a10 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
23a20 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
23a30 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
23a40 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
23a50 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
23a60 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
23a70 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
23a80 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
23a90 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
23aa0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
23ab0 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
23ac0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
23ad0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
23ae0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
23af0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
23b00 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
23b10 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
23b20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
23b30 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
23b40 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
23b50 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
23b60 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
23b70 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
23b80 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
23b90 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
23ba0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
23bb0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
23bc0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
23bd0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
23be0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
23bf0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
23c00 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
23c10 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
23c20 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
23c30 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
23c40 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
23c50 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
23c60 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
23c70 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
23c80 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
23c90 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
23ca0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
23cb0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
23cc0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
23cd0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
23ce0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
23cf0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
23d00 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
23d10 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
23d20 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
23d30 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
23d40 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
23d50 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
23d60 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
23d70 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
23d80 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
23d90 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
23da0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
23db0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
23dc0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
23dd0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
23de0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
23df0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
23e00 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
23e10 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
23e20 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23e30 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
23e40 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
23e50 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
23e60 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
23e70 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23e80 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
23e90 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
23ea0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
23eb0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
23ec0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
23ed0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
23ee0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
23ef0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
23f00 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
23f10 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23f20 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23f30 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
23f40 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
23f50 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
23f60 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
23f70 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
23f80 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
23f90 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
23fa0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
23fb0 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
23fc0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
23fd0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
23fe0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
23ff0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
24000 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
24010 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
24020 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
24030 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
24040 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
24050 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
24060 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
24070 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
24080 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
24090 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
240a0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
240b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
240c0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
240d0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
240e0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
240f0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
24100 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
24110 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
24120 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
24130 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
24140 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
24150 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
24160 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
24170 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
24180 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
24190 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
241a0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
241b0 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
241c0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
241d0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
241e0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
241f0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
24200 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
24210 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
24220 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
24230 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
24240 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
24250 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
24260 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
24270 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
24280 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
24290 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
242a0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
242b0 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
242c0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
242d0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
242e0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
242f0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
24300 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
24310 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
24320 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
24330 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
24340 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
24350 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
24360 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
24370 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
24380 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
24390 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
243a0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
243b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
243c0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
243d0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
243e0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
243f0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
24400 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
24410 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
24420 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
24430 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
24440 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
24450 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
24460 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
24470 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
24480 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
24490 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
244a0 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
244b0 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
244c0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
244d0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
244e0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
244f0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
24500 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
24510 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
24520 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
24530 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
24540 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
24550 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
24560 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
24570 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
24580 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
24590 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
245a0 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
245b0 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
245c0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
245d0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
245e0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
245f0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
24600 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
24610 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
24620 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
24630 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
24640 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
24650 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
24660 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
24670 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
24680 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
24690 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
246a0 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
246b0 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
246c0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
246d0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
246e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
246f0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
24700 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
24710 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
24720 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
24730 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
24740 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
24750 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
24760 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
24770 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
24780 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
24790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
247a0 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
247b0 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
247c0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
247d0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
247e0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
247f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
24800 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
24810 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
24820 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
24830 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
24840 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
24850 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
24860 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
24870 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
24880 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
24890 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
248a0 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
248b0 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
248c0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
248d0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
248e0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
248f0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
24900 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
24910 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
24920 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
24930 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
24940 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
24950 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
24960 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
24970 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
24980 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
24990 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
249a0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
249b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
249c0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
249d0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
249e0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
249f0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
24a00 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
24a10 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
24a20 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
24a30 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
24a40 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
24a50 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
24a60 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
24a70 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
24a80 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
24a90 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
24aa0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
24ab0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
24ac0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
24ad0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
24ae0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
24af0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
24b00 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
24b10 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
24b20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24b30 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
24b40 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
24b50 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
24b60 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
24b70 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
24b80 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
24b90 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24ba0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
24bb0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
24bc0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24bd0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
24be0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
24bf0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
24c00 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
24c10 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
24c20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
24c30 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
24c40 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
24c50 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
24c60 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
24c70 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
24c80 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
24c90 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
24ca0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
24cb0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
24cc0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
24cd0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
24ce0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
24cf0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
24d00 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
24d10 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
24d20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
24d30 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
24d40 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
24d50 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
24d60 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
24d70 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
24d80 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
24d90 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
24da0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
24db0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
24dc0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24dd0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
24de0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
24df0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24e00 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
24e10 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
24e20 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
24e30 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
24e40 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
24e50 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
24e60 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24e70 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
24e80 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
24e90 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
24ea0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
24eb0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
24ec0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
24ed0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
24ee0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
24ef0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
24f00 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
24f10 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
24f20 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
24f30 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
24f40 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
24f50 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
24f60 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
24f70 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
24f80 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
24f90 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
24fa0 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
24fb0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
24fc0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
24fd0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
24fe0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
24ff0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
25000 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
25010 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
25020 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
25030 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
25040 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
25050 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
25060 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
25070 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
25080 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
25090 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
250a0 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
250b0 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
250c0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
250d0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
250e0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
250f0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
25100 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
25110 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
25120 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
25130 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
25140 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
25150 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
25160 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
25170 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
25180 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
25190 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
251a0 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
251b0 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
251c0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
251d0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
251e0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
251f0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
25200 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
25210 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
25220 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
25230 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
25240 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
25250 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
25260 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
25270 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
25280 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
25290 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
252a0 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
252b0 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
252c0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
252d0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
252e0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
252f0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
25300 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
25310 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
25320 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
25330 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
25340 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
25350 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
25360 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
25370 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
25380 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
25390 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
253a0 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
253b0 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
253c0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
253d0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
253e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
253f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25400 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
25410 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
25420 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
25430 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
25440 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
25450 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
25460 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
25470 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
25480 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
25490 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
254a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
254b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
254c0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
254d0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
254e0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
254f0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
25500 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
25510 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
25520 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
25530 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
25540 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
25550 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25560 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
25570 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25580 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
25590 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
255a0 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
255b0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
255c0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
255d0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
255e0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
255f0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
25600 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
25610 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
25620 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25630 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
25640 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
25650 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
25660 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
25670 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
25680 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
25690 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
256a0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
256b0 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
256c0 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
256d0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
256e0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
256f0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
25700 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25710 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
25720 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
25730 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
25740 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
25750 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
25760 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
25770 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
25780 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
25790 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
257a0 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
257b0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
257c0 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
257d0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
257e0 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
257f0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
25800 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
25810 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
25820 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25830 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
25840 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
25850 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
25860 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
25870 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
25880 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
25890 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
258a0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
258b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
258c0 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
258d0 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
258e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
258f0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
25900 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
25910 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
25920 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
25930 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
25940 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
25950 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
25960 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
25970 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
25980 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
25990 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
259a0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
259b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
259c0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
259d0 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
259e0 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
259f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
25a00 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
25a10 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
25a20 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
25a30 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
25a40 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
25a50 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
25a60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
25a70 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
25a80 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
25a90 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
25aa0 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
25ab0 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
25ac0 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
25ad0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
25ae0 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
25af0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
25b00 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
25b10 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
25b20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
25b30 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
25b40 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
25b50 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
25b60 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
25b70 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
25b80 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
25b90 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
25ba0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
25bb0 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
25bc0 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
25bd0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
25be0 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
25bf0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
25c00 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
25c10 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
25c20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
25c30 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
25c40 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
25c50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
25c60 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
25c70 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
25c80 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
25c90 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
25ca0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
25cb0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
25cc0 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
25cd0 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
25ce0 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
25cf0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
25d00 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
25d10 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
25d20 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
25d30 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
25d40 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
25d50 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
25d60 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
25d70 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
25d80 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
25d90 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25da0 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
25db0 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
25dc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
25dd0 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
25de0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
25df0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
25e00 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
25e10 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
25e20 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
25e30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
25e40 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
25e50 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
25e60 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
25e70 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
25e80 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
25e90 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
25ea0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
25eb0 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
25ec0 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
25ed0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
25ee0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
25ef0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
25f00 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
25f10 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
25f20 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
25f30 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
25f40 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
25f50 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
25f60 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
25f70 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
25f80 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
25f90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
25fa0 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e3.**.** ^If the
25fb0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71 6c   most recent sql
25fc0 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 20  ite3_* API call 
25fd0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
25fe0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
25ff0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69 6c  nnection] D fail
26000 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ed, then the sql
26010 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29 20  ite3_errcode(D) 
26020 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
26030 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
26040 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
26050 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  r [extended resu
26060 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 61  lt code] for tha
26070 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a 2a  t.** API call..*
26080 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65  * If the most re
26090 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77 61  cent API call wa
260a0 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a 2a  s successful,.**
260b0 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
260c0 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
260d0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
260e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
260f0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
26100 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
26110 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
26120 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
26130 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
26140 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
26150 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
26160 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
26170 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
26180 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
26190 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
261a0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
261b0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
261c0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
261d0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
261e0 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
261f0 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
26200 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
26210 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
26220 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
26230 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
26240 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
26250 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
26260 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
26270 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
26280 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
26290 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
262a0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
262b0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
262c0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
262d0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
262e0 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
262f0 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
26300 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
26310 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
26320 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
26330 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
26340 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
26350 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26360 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
26370 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
26380 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
26390 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
263a0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
263b0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
263c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
263d0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
263e0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
263f0 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
26400 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
26410 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
26420 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
26430 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
26440 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
26450 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
26460 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
26470 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
26480 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
26490 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
264a0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
264b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
264c0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
264d0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
264e0 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
264f0 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
26500 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
26510 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
26520 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
26530 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
26540 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
26550 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
26560 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
26570 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
26580 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
26590 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
265a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
265b0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
265c0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
265d0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
265e0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
265f0 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
26600 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
26610 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
26620 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
26630 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
26640 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
26650 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
26660 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
26670 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
26680 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
26690 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
266a0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
266b0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
266c0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
266d0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
266e0 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
266f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
26700 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
26710 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
26720 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
26730 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
26740 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
26750 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
26760 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
26770 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
26780 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
26790 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
267a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
267b0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
267c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
267d0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
267e0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
267f0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
26800 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26810 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
26820 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
26830 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
26840 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
26850 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26860 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
26870 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
26880 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
26890 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
268a0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
268b0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
268c0 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
268d0 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
268e0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
268f0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
26900 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
26910 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
26920 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
26930 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
26940 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
26950 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
26960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26970 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
26980 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
26990 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
269a0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
269b0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
269c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
269d0 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
269e0 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
269f0 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
26a00 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
26a10 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
26a20 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
26a30 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
26a40 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
26a50 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
26a60 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
26a70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
26a80 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
26a90 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
26aa0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
26ab0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
26ac0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
26ad0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
26ae0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
26af0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
26b00 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
26b10 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
26b20 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
26b30 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
26b40 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
26b50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
26b60 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
26b70 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
26b80 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
26b90 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
26ba0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
26bb0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
26bc0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
26bd0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
26be0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
26bf0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
26c00 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
26c10 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
26c20 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
26c30 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
26c40 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
26c50 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
26c60 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
26c70 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
26c80 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
26c90 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
26ca0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
26cb0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
26cc0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
26cd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26ce0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
26cf0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
26d00 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
26d10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
26d20 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
26d30 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
26d40 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
26d50 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
26d60 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
26d70 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
26d80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
26d90 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
26da0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
26db0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
26dc0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
26dd0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
26de0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
26df0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
26e00 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
26e10 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
26e20 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
26e30 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
26e40 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
26e50 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
26e60 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
26e70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
26e80 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
26e90 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
26ea0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
26eb0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
26ec0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
26ed0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
26ee0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
26ef0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
26f00 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
26f10 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
26f20 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
26f30 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
26f40 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
26f50 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
26f60 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
26f70 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26f80 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
26f90 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
26fa0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
26fb0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
26fc0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
26fd0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
26fe0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
26ff0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
27000 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
27010 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
27020 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
27030 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
27040 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
27050 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
27060 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
27070 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
27080 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
27090 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
270a0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
270b0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
270c0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
270d0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
270e0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
270f0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
27100 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
27110 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
27120 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
27130 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
27140 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
27150 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
27160 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
27170 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
27180 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
27190 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
271a0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
271b0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
271c0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
271d0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
271e0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
271f0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
27200 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
27210 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
27220 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
27230 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
27240 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
27250 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
27260 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
27270 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
27280 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
27290 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
272a0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
272b0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
272c0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
272d0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
272e0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
272f0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
27300 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
27310 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
27320 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
27330 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
27340 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
27350 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
27360 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
27370 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
27380 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
27390 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
273a0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
273b0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
273c0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
273d0 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ases..*/.int sql
273e0 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74  ite3_limit(sqlit
273f0 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74  e3*, int id, int
27400 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a   newVal);../*.**
27410 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
27420 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f  ime Limit Catego
27430 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ries.** KEYWORDS
27440 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  : {limit categor
27450 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67  y} {*limit categ
27460 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ories}.**.** The
27470 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66  se constants def
27480 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66  ine various perf
27490 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a  ormance limits.*
274a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f  * that can be lo
274b0 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d  wered at run-tim
274c0 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  e using [sqlite3
274d0 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68  _limit()]..** Th
274e0 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68  e synopsis of th
274f0 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68  e meanings of th
27500 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73  e various limits
27510 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e   is shown below.
27520 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69  .** Additional i
27530 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76  nformation is av
27540 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69  ailable at [limi
27550 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53  ts | Limits in S
27560 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64  QLite]..**.** <d
27570 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  l>.** [[SQLITE_L
27580 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  IMIT_LENGTH]] ^(
27590 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
275a0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
275b0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
275c0 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69  size of any stri
275d0 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61  ng or BLOB or ta
275e0 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65  ble row, in byte
275f0 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  s.<dd>)^.**.** [
27600 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  [SQLITE_LIMIT_SQ
27610 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  L_LENGTH]] ^(<dt
27620 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51  >SQLITE_LIMIT_SQ
27630 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  L_LENGTH</dt>.**
27640 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27650 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51   length of an SQ
27660 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20  L statement, in 
27670 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  bytes.</dd>)^.**
27680 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
27690 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64  IT_COLUMN]] ^(<d
276a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
276b0 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  OLUMN</dt>.** <d
276c0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
276d0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
276e0 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e  in a table defin
276f0 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a  ition or in the.
27700 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ** result set of
27710 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74   a [SELECT] or t
27720 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27730 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27740 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69  an index.** or i
27750 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72  n an ORDER BY or
27760 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65   GROUP BY clause
27770 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27780 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  [SQLITE_LIMIT_EX
27790 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  PR_DEPTH]] ^(<dt
277a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58  >SQLITE_LIMIT_EX
277b0 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  PR_DEPTH</dt>.**
277c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
277d0 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61   depth of the pa
277e0 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20  rse tree on any 
277f0 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e  expression.</dd>
27800 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27810 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
27820 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e  _SELECT]] ^(<dt>
27830 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
27840 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74  POUND_SELECT</dt
27850 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27860 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
27870 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75  erms in a compou
27880 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  nd SELECT statem
27890 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ent.</dd>)^.**.*
278a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
278b0 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74  _VDBE_OP]] ^(<dt
278c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  >SQLITE_LIMIT_VD
278d0 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  BE_OP</dt>.** <d
278e0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
278f0 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74  mber of instruct
27900 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61  ions in a virtua
27910 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61  l machine progra
27920 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70  m.** used to imp
27930 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74  lement an SQL st
27940 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c  atement.  This l
27950 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72  imit is not curr
27960 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65  ently.** enforce
27970 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d  d, though that m
27980 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e  ight be added in
27990 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
279a0 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
279b0 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
279c0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  [[SQLITE_LIMIT_F
279d0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28  UNCTION_ARG]] ^(
279e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
279f0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64  _FUNCTION_ARG</d
27a00 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27a10 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27a20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66  arguments on a f
27a30 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  unction.</dd>)^.
27a40 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27a50 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20  IMIT_ATTACHED]] 
27a60 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27a70 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e  IT_ATTACHED</dt>
27a80 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27a90 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41  mum number of [A
27aa0 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64  TTACH | attached
27ab0 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f   databases].)^</
27ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
27ad0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
27ae0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a  TTERN_LENGTH]].*
27af0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
27b00 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
27b10 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  N_LENGTH</dt>.**
27b20 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27b30 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70   length of the p
27b40 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20  attern argument 
27b50 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72  to the [LIKE] or
27b60 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61  .** [GLOB] opera
27b70 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tors.</dd>)^.**.
27b80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27b90 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27ba0 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  R]].** ^(<dt>SQL
27bb0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27bc0 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
27bd0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27be0 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
27bf0 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
27c00 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
27c10 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  ement.)^.**.** [
27c20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  [SQLITE_LIMIT_TR
27c30 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28  IGGER_DEPTH]] ^(
27c40 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27c50 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
27c60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27c70 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
27c80 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
27c90 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
27ca0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27cb0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
27cc0 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  DS]] ^(<dt>SQLIT
27cd0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
27ce0 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  HREADS</dt>.** <
27cf0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
27d00 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61  umber of auxilia
27d10 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64  ry worker thread
27d20 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a  s that a single.
27d30 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
27d40 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72  tement] may star
27d50 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  t.</dd>)^.** </d
27d60 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
27d70 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
27d80 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
27d90 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53       0.#define S
27da0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
27db0 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
27dc0 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
27dd0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
27de0 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20  UMN             
27df0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
27e00 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58   SQLITE_LIMIT_EX
27e10 50 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  PR_DEPTH        
27e20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
27e30 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
27e40 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20  OMPOUND_SELECT  
27e50 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
27e60 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27e70 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20  VDBE_OP         
27e80 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
27e90 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27ea0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20  _FUNCTION_ARG   
27eb0 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
27ec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27ed0 54 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20  T_ATTACHED      
27ee0 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
27ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27f00 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
27f10 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23  LENGTH       8.#
27f20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27f30 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
27f40 42 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a  BER           9.
27f50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27f60 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27f70 54 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30  TH            10
27f80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27f90 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
27fa0 45 41 44 53 20 20 20 20 20 20 20 20 20 20 20 31  EADS           1
27fb0 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  1../*.** CAPI3RE
27fc0 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20  F: Compiling An 
27fd0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
27fe0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
27ff0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c  statement compil
28000 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
28010 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52  qlite3.** CONSTR
28020 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73  UCTOR: sqlite3_s
28030 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65  tmt.**.** To exe
28040 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72  cute an SQL quer
28050 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73 74  y, it must first
28060 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74   be compiled int
28070 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a  o a byte-code.**
28080 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f   program using o
28090 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ne of these rout
280a0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ines..**.** The 
280b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20  first argument, 
280c0 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61  "db", is a [data
280d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
280e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
280f0 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73  .** prior succes
28100 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71  sful call to [sq
28110 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
28120 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
28130 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
28140 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68  3_open16()].  Th
28150 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
28160 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68  ction must not h
28170 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e  ave been closed.
28180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  .**.** The secon
28190 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71  d argument, "zSq
281a0 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74 65  l", is the state
281b0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
281c0 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20  led, encoded.** 
281d0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
281e0 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20  or UTF-16.  The 
281f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
28200 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
28210 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e  epare_v2().** in
28220 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54 46  terfaces use UTF
28230 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  -8, and sqlite3_
28240 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64 20  prepare16() and 
28250 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28260 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54  6_v2().** use UT
28270 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  F-16..**.** ^If 
28280 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65  the nByte argume
28290 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  nt is negative, 
282a0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
282b0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
282c0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
282d0 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
282e0 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
282f0 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e  n it is the.** n
28300 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 72  umber of bytes r
28310 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
28320 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72  ^If nByte is zer
28330 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61  o, then no prepa
28340 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
28350 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a   is generated..*
28360 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  * If the caller 
28370 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65 20 73  knows that the s
28380 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
28390 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
283a0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20  , then.** there 
283b0 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f  is a small perfo
283c0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
283d0 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   to passing an n
283e0 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
283f0 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  hat.** is the nu
28400 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
28410 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
28420 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f  g <i>including</
28430 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65  i>.** the nul-te
28440 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
28450 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
28460 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
28470 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
28480 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
28490 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
284a0 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
284b0 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
284c0 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
284d0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
284e0 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
284f0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
28500 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
28510 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
28520 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
28530 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
28540 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
28550 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
28560 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
28570 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28580 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
28590 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
285a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
285b0 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
285c0 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
285d0 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
285e0 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
285f0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
28600 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
28610 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
28620 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
28630 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
28640 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
28650 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
28660 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
28670 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
28680 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
28690 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
286a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
286b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
286c0 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
286d0 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
286e0 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
286f0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
28700 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
28710 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
28720 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
28730 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
28740 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
28750 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
28760 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
28770 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
28780 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
28790 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
287a0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
287b0 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
287c0 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
287d0 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
287e0 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
287f0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
28800 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
28810 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
28820 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
28830 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
28840 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
28850 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
28860 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
28870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28880 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
28890 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
288a0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
288b0 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
288c0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
288d0 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
288e0 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
288f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28900 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
28910 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
28920 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
28930 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
28940 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
28950 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
28960 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
28970 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
28980 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
28990 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
289a0 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
289b0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
289c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
289d0 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
289e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
289f0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
28a00 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61  again. As many a
28a10 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43  s [SQLITE_MAX_SC
28a20 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72  HEMA_RETRY].** r
28a30 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75  etries will occu
28a40 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33  r before sqlite3
28a50 5f 73 74 65 70 28 29 20 67 69 76 65 73 20 75 70  _step() gives up
28a60 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20   and returns an 
28a70 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  error..** </li>.
28a80 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
28a90 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
28aa0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
28ab0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
28ac0 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
28ad0 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
28ae0 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
28af0 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
28b00 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
28b10 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
28b20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28b30 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
28b40 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
28b50 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
28b60 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
28b70 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
28b80 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
28b90 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
28ba0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
28bb0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
28bc0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
28bd0 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
28be0 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
28bf0 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
28c00 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
28c10 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
28c20 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
28c30 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
28c40 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
28c50 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
28c60 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
28c70 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
28c80 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
28c90 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
28ca0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
28cb0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
28cc0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
28cd0 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
28ce0 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
28cf0 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
28d00 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
28d10 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
28d20 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
28d30 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
28d40 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
28d50 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
28d60 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
28d70 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
28d80 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
28d90 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
28da0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
28db0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
28dc0 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
28dd0 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
28de0 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
28df0 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
28e00 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
28e10 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
28e20 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
28e30 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
28e40 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
28e50 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
28e60 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
28e70 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
28e80 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
28e90 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
28ea0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
28eb0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
28ec0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
28ed0 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  3] compile-time 
28ee0 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
28ef0 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  d..** </li>.** <
28f00 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  /ol>.*/.int sqli
28f10 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
28f20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28f30 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28f40 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
28f50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
28f60 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
28f70 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
28f80 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28f90 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28fa0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28fb0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28fc0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28fd0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28fe0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28ff0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
29000 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
29010 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
29020 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
29030 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
29040 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
29050 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29060 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
29070 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
29080 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
29090 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
290a0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
290b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
290c0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
290d0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
290e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
290f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
29100 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
29110 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
29120 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
29130 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
29140 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
29150 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
29160 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
29170 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
29180 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
29190 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
291a0 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65  pare16(.  sqlite
291b0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
291c0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
291d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
291e0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
291f0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
29200 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
29210 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
29220 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
29230 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
29240 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
29250 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
29260 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
29270 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
29280 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
29290 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
292a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
292b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
292c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
292d0 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
292e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
292f0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
29300 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
29310 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
29320 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
29330 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
29340 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
29350 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
29360 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
29370 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
29380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
29390 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
293a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
293b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
293c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
293d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
293e0 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
293f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
29400 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
29410 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
29420 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29430 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
29440 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
29450 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
29460 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  t.**.** ^This in
29470 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
29480 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
29490 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
294a0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
294b0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
294c0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
294d0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
294e0 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
294f0 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
29500 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
29510 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29520 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
29530 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
29540 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
29550 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
29560 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
29570 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29580 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
29590 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
295a0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
295b0 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
295c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
295d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
295e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
295f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29600 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
29610 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
29620 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
29630 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
29640 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
29650 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
29660 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
29670 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
29680 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
29690 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
296a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
296b0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
296c0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
296d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
296e0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
296f0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
29700 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
29710 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
29720 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
29730 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
29740 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
29750 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
29760 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
29770 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
29780 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
29790 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
297a0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
297b0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
297c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
297d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
297e0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
297f0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
29800 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
29810 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
29820 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
29830 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29840 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
29850 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
29860 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
29870 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
29880 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
29890 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
298a0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
298b0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
298c0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
298d0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
298e0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
298f0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
29900 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
29910 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
29920 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
29930 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
29940 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
29950 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
29960 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
29970 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
29980 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
29990 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
299a0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
299b0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
299c0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
299d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
299e0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
299f0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
29a00 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
29a10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
29a20 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
29a30 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
29a40 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
29a50 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
29a60 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
29a70 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
29a80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
29a90 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
29aa0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
29ab0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
29ac0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
29ad0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74 20  on disk..*/.int 
29ae0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29af0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
29b00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
29b10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
29b20 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
29b30 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
29b40 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
29b50 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
29b60 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
29b70 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29b80 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
29b90 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
29ba0 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
29bb0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
29bc0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
29bd0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
29be0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
29bf0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29c00 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65 69 74  S)] but has neit
29c10 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  her run to compl
29c20 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a  etion (returned.
29c30 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
29c40 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
29c50 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20  tep(S)]) nor.** 
29c60 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
29c70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29c80 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
29c90 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
29ca0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
29cb0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
29cc0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29cd0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
29ce0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
29cf0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
29d00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
29d10 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
29d20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
29d30 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
29d40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
29d50 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
29d60 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
29d70 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
29d80 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
29d90 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
29da0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
29db0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
29dc0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
29dd0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
29de0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
29df0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
29e00 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
29e10 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
29e20 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
29e30 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
29e40 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
29e50 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
29e60 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
29e70 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
29e80 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
29e90 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
29ea0 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
29eb0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29ec0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
29ed0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29ee0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
29ef0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
29f00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
29f10 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29f20 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
29f30 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29f40 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
29f50 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
29f60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
29f70 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
29f80 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
29f90 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
29fa0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
29fb0 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
29fc0 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
29fd0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
29fe0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
29ff0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2a000 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a010 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2a020 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2a030 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2a040 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2a050 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2a060 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2a070 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2a080 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2a090 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2a0a0 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2a0b0 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2a0c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2a0d0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2a0e0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2a0f0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2a100 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2a110 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2a120 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2a130 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2a140 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2a150 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2a160 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2a170 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2a180 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2a190 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2a1a0 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  alue.  The.** [s
2a1b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
2a1c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61  ()] interface ca
2a1d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e  n be used to con
2a1e0 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a  struct a new .**
2a1f0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2a200 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e  e3_value from an
2a210 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2a220 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  ite3_value..**.*
2a230 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f  * The terms "pro
2a240 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70  tected" and "unp
2a250 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20  rotected" refer 
2a260 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  to whether or no
2a270 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20  t.** a mutex is 
2a280 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e  held.  An intern
2a290 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  al mutex is held
2a2a0 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64   for a protected
2a2b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2a2c0 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20  e object but no 
2a2d0 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f  mutex is held fo
2a2e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2a2f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2a300 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51  e object.  If SQ
2a310 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2a320 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68   to be single-th
2a330 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20  readed.** (with 
2a340 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2a350 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b  FE=0] and with [
2a360 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2a370 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20  fe()] returning 
2a380 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69  0).** or if SQLi
2a390 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65  te is run in one
2a3a0 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65   of reduced mute
2a3b0 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c  x modes .** [SQL
2a3c0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
2a3d0 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c  ETHREAD] or [SQL
2a3e0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2a3f0 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20  THREAD].** then 
2a400 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74  there is no dist
2a410 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2a420 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2a430 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2a440 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a450 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20  ts and they can 
2a460 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61  be used intercha
2a470 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65  ngeably.  Howeve
2a480 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75  r,.** for maximu
2a490 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69  m code portabili
2a4a0 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ty it is recomme
2a4b0 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
2a4c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20  ations.** still 
2a4d0 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
2a4e0 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f  tion between pro
2a4f0 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f  tected and unpro
2a500 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2a510 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2a520 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74  even when not st
2a530 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e  rictly required.
2a540 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a550 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2a560 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65  s that are passe
2a570 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20  d as parameters 
2a580 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  into the.** impl
2a590 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61  ementation of [a
2a5a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a5b0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2a5c0 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e  ] are protected.
2a5d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a5e0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65  _value object re
2a5f0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
2a600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2a610 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65  ue()] is unprote
2a620 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65  cted..** Unprote
2a630 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2a640 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f  ue objects may o
2a650 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2a660 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2a670 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64  ult_value()] and
2a680 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2a690 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  alue()]..** The 
2a6a0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2a6b0 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61  lob | sqlite3_va
2a6c0 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69  lue_type()] fami
2a6d0 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  ly of.** interfa
2a6e0 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74  ces require prot
2a6f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a700 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a  lue objects..*/.
2a710 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d  typedef struct M
2a720 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  em sqlite3_value
2a730 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a740 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  F: SQL Function 
2a750 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a  Context Object.*
2a760 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74  *.** The context
2a770 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c   in which an SQL
2a780 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74   function execut
2a790 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  es is stored in 
2a7a0 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  an.** sqlite3_co
2a7b0 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e  ntext object.  ^
2a7c0 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
2a7d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2a7e0 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77  object.** is alw
2a7f0 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65  ays first parame
2a800 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74  ter to [applicat
2a810 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a820 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54  functions]..** T
2a830 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2a840 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2a850 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2a860 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69  on will pass thi
2a870 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72  s.** pointer thr
2a880 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20  ough into calls 
2a890 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  to [sqlite3_resu
2a8a0 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  lt_int | sqlite3
2a8b0 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b  _result()],.** [
2a8c0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2a8d0 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73  e_context()], [s
2a8e0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
2a8f0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2a900 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2a910 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  le()], [sqlite3_
2a920 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a  get_auxdata()],.
2a930 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74  ** and/or [sqlit
2a940 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
2a950 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
2a960 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ruct sqlite3_con
2a970 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  text sqlite3_con
2a980 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  text;../*.** CAP
2a990 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56  I3REF: Binding V
2a9a0 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65  alues To Prepare
2a9b0 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d Statements.** 
2a9c0 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20  KEYWORDS: {host 
2a9d0 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74  parameter} {host
2a9e0 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f   parameters} {ho
2a9f0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2aa00 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  e}.** KEYWORDS: 
2aa10 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20  {SQL parameter} 
2aa20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d  {SQL parameters}
2aa30 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   {parameter bind
2aa40 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ing}.** METHOD: 
2aa50 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2aa60 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20  ** ^(In the SQL 
2aa70 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69  statement text i
2aa80 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
2aa90 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2aaa0 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c  nd its variants,
2aab0 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79  .** literals may
2aac0 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20   be replaced by 
2aad0 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68  a [parameter] th
2aae0 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f  at matches one o
2aaf0 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74  f following.** t
2ab00 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20  emplates:.**.** 
2ab10 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a  <ul>.** <li>  ?.
2ab20 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a  ** <li>  ?NNN.**
2ab30 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c   <li>  :VVV.** <
2ab40 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69  li>  @VVV.** <li
2ab50 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e  >  $VVV.** </ul>
2ab60 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65  .**.** In the te
2ab70 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e  mplates above, N
2ab80 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  NN represents an
2ab90 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c   integer literal
2aba0 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70  ,.** and VVV rep
2abb0 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61  resents an alpha
2abc0 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69  numeric identifi
2abd0 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75  er.)^  ^The valu
2abe0 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70  es of these.** p
2abf0 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20  arameters (also 
2ac00 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72  called "host par
2ac10 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72  ameter names" or
2ac20 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   "SQL parameters
2ac30 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74  ").** can be set
2ac40 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
2ac50 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2ac60 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72  ines defined her
2ac70 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2ac80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2ac90 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2aca0 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73  _*() routines is
2acb0 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69   always.** a poi
2acc0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
2acd0 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
2ace0 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a  t returned from.
2acf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2ad00 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73  are_v2()] or its
2ad10 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a   variants..**.**
2ad20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
2ad30 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2ad40 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61  ex of the SQL pa
2ad50 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65  rameter to be se
2ad60 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d  t..** ^The leftm
2ad70 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ost SQL paramete
2ad80 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2ad90 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20  f 1.  ^When the 
2ada0 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51  same named.** SQ
2adb0 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75  L parameter is u
2adc0 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  sed more than on
2add0 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ce, second and s
2ade0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63  ubsequent.** occ
2adf0 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68  urrences have th
2ae00 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20  e same index as 
2ae10 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72  the first occurr
2ae20 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e  ence..** ^The in
2ae30 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61  dex for named pa
2ae40 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20  rameters can be 
2ae50 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20  looked up using 
2ae60 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
2ae70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2ae80 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64  ndex()] API if d
2ae90 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e  esired.  ^The in
2aea0 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e  dex.** for "?NNN
2aeb0 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  " parameters is 
2aec0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e  the value of NNN
2aed0 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61  ..** ^The NNN va
2aee0 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77  lue must be betw
2aef0 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73  een 1 and the [s
2af00 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
2af10 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51  ** parameter [SQ
2af20 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
2af30 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66  BLE_NUMBER] (def
2af40 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29  ault value: 999)
2af50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
2af60 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
2af70 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64  he value to bind
2af80 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
2af90 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
2afa0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
2afb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2afc0 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2afd0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2afe0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2aff0 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c  _blob() is a NUL
2b000 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74  L pointer then t
2b010 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2b020 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65  ter.** is ignore
2b030 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65  d and the end re
2b040 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65  sult is the same
2b050 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   as sqlite3_bind
2b060 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  _null()..**.** ^
2b070 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
2b080 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
2b090 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
2b0a0 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
2b0b0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
2b0c0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
2b0d0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
2b0e0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
2b0f0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2b100 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
2b110 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
2b120 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2b130 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
2b140 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
2b150 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2b160 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20  te3_bind_text() 
2b170 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2b180 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e  text16().** is n
2b190 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
2b1a0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2b1b0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2b1c0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2b1d0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2b1e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2b1f0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72  ..** If the four
2b200 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2b210 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b220 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c  b() is negative,
2b230 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68   then.** the beh
2b240 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2b250 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d  ed..** If a non-
2b260 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20  negative fourth 
2b270 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f  parameter is pro
2b280 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33  vided to sqlite3
2b290 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20  _bind_text().** 
2b2a0 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2b2b0 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69  text16() or sqli
2b2c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2b2d0 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70  ) then.** that p
2b2e0 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2b2f0 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2b300 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2b310 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2b320 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2b330 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2b340 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2b350 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2b360 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2b370 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2b380 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2b390 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2b3a0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2b3b0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2b3c0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2b3d0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2b3e0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2b3f0 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2b400 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2b410 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2b420 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2b430 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2b440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2b450 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
2b460 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69  he BLOB and stri
2b470 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72  ng binding inter
2b480 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65  faces.** is a de
2b490 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f  structor used to
2b4a0 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
2b4b0 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e  BLOB or.** strin
2b4c0 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68  g after SQLite h
2b4d0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
2b4e0 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72   it.  ^The destr
2b4f0 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a  uctor is called.
2b500 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ** to dispose of
2b510 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72   the BLOB or str
2b520 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2b530 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49  call to bind API
2b540 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74   fails..** ^If t
2b550 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2b560 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
2b570 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
2b580 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
2b590 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
2b5a0 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
2b5b0 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
2b5c0 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
2b5d0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
2b5e0 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
2b5f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
2b600 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
2b610 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
2b620 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
2b630 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
2b640 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
2b650 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2b660 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
2b670 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
2b680 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2b690 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2b6a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  s..**.** ^The si
2b6b0 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  xth argument to 
2b6c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b6d0 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e  t64() must be on
2b6e0 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  e of.** [SQLITE_
2b6f0 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
2b700 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  TF16], [SQLITE_U
2b710 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c  TF16BE], or [SQL
2b720 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20  ITE_UTF16LE].** 
2b730 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65  to specify the e
2b740 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74  ncoding of the t
2b750 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64  ext in the third
2b760 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a   parameter.  If.
2b770 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67  ** the sixth arg
2b780 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2b790 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69  _bind_text64() i
2b7a0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
2b7b0 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75  .** allowed valu
2b7c0 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20  es shown above, 
2b7d0 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65  or if the text e
2b7e0 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2b7f0 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  rent.** from the
2b800 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66   encoding specif
2b810 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68  ied by the sixth
2b820 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
2b830 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
2b840 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2b850 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b860 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2b870 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2b880 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2b890 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2b8a0 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2b8b0 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2b8c0 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2b8d0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2b8e0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2b8f0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2b900 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2b910 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2b920 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2b930 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2b940 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2b950 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2b960 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2b970 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2b980 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2b990 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2b9a0 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2b9b0 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2b9c0 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2b9d0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2b9e0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2b9f0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2ba00 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2ba10 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2ba20 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2ba30 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2ba40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2ba50 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2ba60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ba70 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2ba80 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2ba90 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2baa0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2bab0 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2bac0 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2bad0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2bae0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2baf0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2bb00 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2bb10 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2bb20 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2bb30 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2bb40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bb50 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2bb60 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2bb70 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2bb80 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2bb90 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2bba0 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2bbb0 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2bbc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2bbd0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2bbe0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2bbf0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2bc00 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2bc10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bc20 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2bc30 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2bc40 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2bc50 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2bc60 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2bc70 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2bc80 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47   ^[SQLITE_TOOBIG
2bc90 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2bca0 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20  ned if the size 
2bcb0 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  of a string or B
2bcc0 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c  LOB.** exceeds l
2bcd0 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79  imits imposed by
2bce0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
2bcf0 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  ([SQLITE_LIMIT_L
2bd00 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53  ENGTH]) or.** [S
2bd10 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48  QLITE_MAX_LENGTH
2bd20 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  ]..** ^[SQLITE_R
2bd30 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2bd40 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2bd50 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2bd60 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2bd70 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2bd80 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2bd90 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2bda0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2bdb0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bdc0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2bdd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bde0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2bdf0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2be00 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2be10 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
2be20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2be30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2be40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2be50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2be60 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
2be70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2be80 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2be90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2bea0 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2beb0 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2bec0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2bed0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2bee0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
2bef0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
2bf00 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
2bf10 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2bf20 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2bf30 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2bf40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2bf50 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2bf60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2bf70 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
2bf80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2bf90 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2bfa0 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2bfb0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2bfc0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63  ite3_stmt*,int,c
2bfd0 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76  onst char*,int,v
2bfe0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2bff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2c000 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
2c010 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2c020 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
2c030 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2c040 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2c050 74 65 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73  text64(sqlite3_s
2c060 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2c070 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
2c080 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20  uint64,.        
2c090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c0a0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c   void(*)(void*),
2c0b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65   unsigned char e
2c0c0 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20 73 71  ncoding);.int sq
2c0d0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2c0e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c0f0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2c100 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
2c110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2c120 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  oblob(sqlite3_st
2c130 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29  mt*, int, int n)
2c140 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2c150 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71  nd_zeroblob64(sq
2c160 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c170 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
2c180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c190 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2c1a0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2c1b0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2c1c0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2c1d0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2c1e0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2c1f0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2c200 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2c210 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2c220 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2c230 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2c240 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2c250 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2c260 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2c270 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2c280 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2c290 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2c2a0 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2c2b0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2c2c0 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2c2d0 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2c2e0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2c2f0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2c300 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2c310 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2c320 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2c330 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2c340 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2c350 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2c360 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2c370 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2c380 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2c390 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2c3a0 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2c3b0 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2c3c0 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2c3d0 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2c3e0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2c3f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c400 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c410 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c430 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c440 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2c450 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c460 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2c470 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2c480 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c490 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
2c4a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c4b0 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
2c4c0 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
2c4d0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2c4e0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2c4f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c500 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
2c510 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2c520 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
2c530 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
2c540 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
2c550 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c560 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
2c570 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
2c580 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
2c590 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
2c5a0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
2c5b0 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
2c5c0 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
2c5d0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
2c5e0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
2c5f0 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
2c600 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
2c610 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
2c620 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
2c630 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
2c640 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
2c650 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
2c660 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
2c670 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2c680 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
2c690 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
2c6a0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
2c6b0 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
2c6c0 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
2c6d0 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
2c6e0 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
2c6f0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
2c700 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
2c710 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
2c720 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
2c730 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
2c740 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
2c750 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
2c760 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
2c770 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
2c780 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
2c790 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2c7a0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
2c7b0 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
2c7c0 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
2c7d0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
2c7e0 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
2c7f0 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
2c800 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
2c810 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
2c820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2c830 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2c840 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c850 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2c860 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2c870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c880 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2c890 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2c8a0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c8b0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2c8c0 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2c8d0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c8e0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2c8f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2c900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c910 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2c920 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2c930 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
2c940 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c950 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2c960 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2c970 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2c980 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2c990 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2c9a0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2c9b0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2c9c0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2c9d0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2c9e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2c9f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2ca00 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2ca10 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2ca20 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2ca30 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2ca40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2ca50 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2ca60 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2ca70 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2ca80 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2ca90 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2caa0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2cab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cac0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2cad0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2cae0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2caf0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2cb00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2cb10 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2cb20 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2cb30 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2cb40 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  _name()]..*/.int
2cb50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2cb60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2cb70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2cb80 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2cb90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2cba0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2cbb0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2cbc0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed Statement.** 
2cbd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2cbe0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  stmt.**.** ^Cont
2cbf0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
2cc00 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
2cc10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cc20 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
2cc30 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
2cc40 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
2cc50 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
2cc60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2cc70 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
2cc80 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
2cc90 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
2cca0 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69  rs to NULL..*/.i
2ccb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  nt sqlite3_clear
2ccc0 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2ccd0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2cce0 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2ccf0 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2cd00 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2cd10 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2cd20 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2cd30 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2cd40 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2cd50 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2cd60 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2cd70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd80 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2cd90 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2cda0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2cdb0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2cdc0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2cdd0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2cde0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2cdf0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2ce00 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2ce10 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73  ount()].*/.int s
2ce20 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ce30 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2ce40 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2ce50 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2ce60 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2ce70 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
2ce80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2ce90 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2cea0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2ceb0 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
2cec0 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
2ced0 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
2cee0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2cef0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cf00 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
2cf10 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
2cf20 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2cf30 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2cf40 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2cf50 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
2cf60 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2cf70 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2cf80 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2cf90 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2cfa0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
2cfb0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
2cfc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2cfd0 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2cfe0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
2cff0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2d000 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2d010 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
2d020 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2d030 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
2d040 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
2d050 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
2d060 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
2d070 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2d080 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
2d090 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
2d0a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d0b0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
2d0c0 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
2d0d0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2d0e0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2d0f0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2d100 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2d110 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2d120 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2d130 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2d140 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2d150 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2d160 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
2d170 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2d180 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
2d190 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2d1a0 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
2d1b0 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
2d1c0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
2d1d0 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
2d1e0 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
2d1f0 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
2d200 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
2d210 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
2d220 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
2d230 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
2d240 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
2d250 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2d260 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2d270 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
2d280 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
2d290 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
2d2a0 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
2d2b0 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
2d2c0 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
2d2d0 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
2d2e0 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
2d2f0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2d300 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
2d310 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
2d320 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
2d330 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
2d340 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
2d350 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
2d360 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d370 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2d380 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73  t*, int N);.cons
2d390 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d3a0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71  column_name16(sq
2d3b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d3c0 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   N);../*.** CAPI
2d3d0 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20  3REF: Source Of 
2d3e0 44 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20  Data In A Query 
2d3f0 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44  Result.** METHOD
2d400 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2d410 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
2d420 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d  ines provide a m
2d430 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e  eans to determin
2d440 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  e the database, 
2d450 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61  table, and.** ta
2d460 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20  ble column that 
2d470 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66  is the origin of
2d480 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
2d490 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a  sult column in.*
2d4a0 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  * [SELECT] state
2d4b0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61  ment..** ^The na
2d4c0 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  me of the databa
2d4d0 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63  se or table or c
2d4e0 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74  olumn can be ret
2d4f0 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68  urned as.** eith
2d500 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54  er a UTF-8 or UT
2d510 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2d520 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f  he _database_ ro
2d530 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a  utines return.**
2d540 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
2d550 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20  me, the _table_ 
2d560 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d570 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20  the table name, 
2d580 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  and.** the origi
2d590 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  n_ routines retu
2d5a0 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61  rn the column na
2d5b0 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  me..** ^The retu
2d5c0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 76  rned string is v
2d5d0 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b  alid until the [
2d5e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d5f0 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64  nt] is destroyed
2d600 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
2d610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
2d620 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
2d630 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
2d640 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
2d650 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
2d660 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2d670 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
2d680 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
2d690 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
2d6a0 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
2d6b0 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a   is requested.**
2d6c0 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66   again in a diff
2d6d0 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a  erent encoding..
2d6e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73  **.** ^The names
2d6f0 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74 68   returned are th
2d700 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c  e original un-al
2d710 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74  iased names of t
2d720 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20  he.** database, 
2d730 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d  table, and colum
2d740 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  n..**.** ^The fi
2d750 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
2d760 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
2d770 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20   is a [prepared 
2d780 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2d790 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2d7a0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2d7b0 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68  on about the Nth
2d7c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72   result column r
2d7d0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68  eturned by.** th
2d7e0 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65  e statement, whe
2d7f0 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f  re N is the seco
2d800 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  nd function argu
2d810 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65  ment..** ^The le
2d820 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  ft-most column i
2d830 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74  s column 0 for t
2d840 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
2d850 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68  *.** ^If the Nth
2d860 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2d870 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e   by the statemen
2d880 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73 69  t is an expressi
2d890 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72  on or.** subquer
2d8a0 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63  y and is not a c
2d8b0 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65  olumn value, the
2d8c0 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66  n all of these f
2d8d0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a  unctions return.
2d8e0 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65  ** NULL.  ^These
2d8f0 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61   routine might a
2d900 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20  lso return NULL 
2d910 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  if a memory allo
2d920 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20  cation error.** 
2d930 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77  occurs.  ^Otherw
2d940 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e  ise, they return
2d950 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2d960 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
2d970 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72  se, table,.** or
2d980 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65   column that que
2d990 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ry result column
2d9a0 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20 66   was extracted f
2d9b0 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77  rom..**.** ^As w
2d9c0 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51  ith all other SQ
2d9d0 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65  Lite APIs, those
2d9e0 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64   whose names end
2d9f0 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75 72   with "16" retur
2da00 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f  n.** UTF-16 enco
2da10 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20  ded strings and 
2da20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69  the other functi
2da30 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38  ons return UTF-8
2da40 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41  ..**.** ^These A
2da50 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61  PIs are only ava
2da60 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69  ilable if the li
2da70 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c  brary was compil
2da80 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
2da90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f  SQLITE_ENABLE_CO
2daa0 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43  LUMN_METADATA] C
2dab0 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79  -preprocessor sy
2dac0 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  mbol..**.** If t
2dad0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2dae0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2daf0 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ore of these rou
2db00 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68  tines against th
2db10 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72  e same.** prepar
2db20 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  ed statement and
2db30 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73   column at the s
2db40 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68  ame time then th
2db50 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a  e results are.**
2db60 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2db70 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2db80 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2db90 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71  e or more.** [sq
2dba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2dbb0 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c  abase_name | col
2dbc0 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74  umn metadata int
2dbd0 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20  erfaces].** for 
2dbe0 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72  the same [prepar
2dbf0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e  ed statement] an
2dc00 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a  d result column.
2dc10 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ** at the same t
2dc20 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73  ime then the res
2dc30 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2dc40 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  ed..*/.const cha
2dc50 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2dc60 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28  n_database_name(
2dc70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2dc80 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2dc90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2dca0 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73  atabase_name16(s
2dcb0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2dcc0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
2dcd0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2dce0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2dcf0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2dd00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2dd10 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
2dd20 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2dd30 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2dd40 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2dd50 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2dd60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2dd70 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2dd80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2dd90 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
2dda0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ddb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ddc0 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
2ddd0 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
2dde0 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  esult.** METHOD:
2ddf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2de00 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
2de10 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
2de20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2de30 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
2de40 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2de50 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2de60 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
2de70 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
2de80 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
2de90 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
2dea0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
2deb0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
2dec0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2ded0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
2dee0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
2def0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
2df00 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
2df10 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
2df20 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2df30 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
2df40 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2df50 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
2df60 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2df70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2df80 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2df90 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
2dfa0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
2dfb0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2dfc0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
2dfd0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
2dfe0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
2dff0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
2e000 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
2e010 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
2e020 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2e030 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
2e040 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
2e050 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
2e060 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
2e070 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
2e080 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
2e090 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
2e0a0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
2e0b0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
2e0c0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
2e0d0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
2e0e0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
2e0f0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
2e100 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
2e110 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
2e120 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
2e130 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
2e140 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
2e150 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
2e160 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
2e170 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
2e180 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
2e190 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
2e1a0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
2e1b0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
2e1c0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
2e1d0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
2e1e0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
2e1f0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
2e200 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
2e210 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
2e220 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
2e230 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
2e240 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
2e250 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  lues..*/.const c
2e260 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2e270 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2e280 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2e290 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2e2a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2e2b0 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73  type16(sqlite3_s
2e2c0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2e2d0 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c  * CAPI3REF: Eval
2e2e0 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74  uate An SQL Stat
2e2f0 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2e300 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e310 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
2e320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e330 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
2e340 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
2e350 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
2e360 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2e370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e380 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
2e390 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2e3a0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
2e3b0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
2e3c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e3d0 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
2e3e0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
2e3f0 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
2e400 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
2e410 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
2e420 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
2e430 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
2e440 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
2e450 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
2e460 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
2e470 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
2e480 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
2e490 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
2e4a0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
2e4b0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
2e4c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
2e4d0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2e4e0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
2e4f0 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
2e500 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
2e510 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2e520 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2e530 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
2e540 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
2e550 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
2e560 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2e570 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
2e580 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
2e590 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2e5a0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
2e5b0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
2e5c0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
2e5d0 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
2e5e0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2e5f0 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
2e600 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
2e610 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
2e620 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
2e630 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
2e640 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
2e650 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
2e660 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2e670 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
2e680 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
2e690 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2e6a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
2e6b0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
2e6c0 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
2e6d0 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
2e6e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
2e6f0 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
2e700 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
2e710 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
2e720 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
2e730 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
2e740 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
2e750 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
2e760 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
2e770 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
2e780 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2e790 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
2e7a0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
2e7b0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
2e7c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
2e7d0 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
2e7e0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
2e7f0 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72  n.** explicit tr
2e800 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79  ansaction then y
2e810 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61  ou should rollba
2e820 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  ck the transacti
2e830 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e  on before.** con
2e840 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  tinuing..**.** ^
2e850 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65  [SQLITE_DONE] me
2e860 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61  ans that the sta
2e870 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73  tement has finis
2e880 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a  hed executing.**
2e890 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20   successfully.  
2e8a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
2e8b0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
2e8c0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69  led again on thi
2e8d0 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  s virtual.** mac
2e8e0 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72  hine without fir
2e8f0 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  st calling [sqli
2e900 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20  te3_reset()] to 
2e910 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61  reset the virtua
2e920 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63  l.** machine bac
2e930 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
2e940 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49   state..**.** ^I
2e950 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
2e960 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74  ent being execut
2e970 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64  ed returns any d
2e980 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ata, then [SQLIT
2e990 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74  E_ROW].** is ret
2e9a0 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20  urned each time 
2e9b0 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74  a new row of dat
2e9c0 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70  a is ready for p
2e9d0 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65  rocessing by the
2e9e0 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20  .** caller. The 
2e9f0 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63  values may be ac
2ea00 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65  cessed using the
2ea10 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
2ea20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73  functions]..** s
2ea30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73  qlite3_step() is
2ea40 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f   called again to
2ea50 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65   retrieve the ne
2ea60 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a  xt row of data..
2ea70 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45  **.** ^[SQLITE_E
2ea80 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74  RROR] means that
2ea90 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f   a run-time erro
2eaa0 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e  r (such as a con
2eab0 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61  straint.** viola
2eac0 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72  tion) has occurr
2ead0 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65  ed.  sqlite3_ste
2eae0 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  p() should not b
2eaf0 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f  e called again o
2eb00 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72  n.** the VM. Mor
2eb10 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61  e information ma
2eb20 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61  y be found by ca
2eb30 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
2eb40 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69  rrmsg()]..** ^Wi
2eb50 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e  th the legacy in
2eb60 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20  terface, a more 
2eb70 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2eb80 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  ode (for example
2eb90 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  ,.** [SQLITE_INT
2eba0 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45  ERRUPT], [SQLITE
2ebb0 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54  _SCHEMA], [SQLIT
2ebc0 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20  E_CORRUPT], and 
2ebd0 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e  so forth).** can
2ebe0 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20   be obtained by 
2ebf0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2ec00 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65  _reset()] on the
2ec10 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2ec20 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74  atement].  ^In t
2ec30 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2ec40 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  e,.** the more s
2ec50 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2ec60 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64  de is returned d
2ec70 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74  irectly by sqlit
2ec80 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a  e3_step()..**.**
2ec90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2eca0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2ecb0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73  this routine was
2ecc0 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70   called inapprop
2ecd0 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68  riately..** Perh
2ece0 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65  aps it was calle
2ecf0 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  d on a [prepared
2ed00 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2ed10 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20   has.** already 
2ed20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  been [sqlite3_fi
2ed30 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2ed40 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68  ed] or on one th
2ed50 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f  at had.** previo
2ed60 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53  usly returned [S
2ed70 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20  QLITE_ERROR] or 
2ed80 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2ed90 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62  Or it could.** b
2eda0 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
2edb0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
2edc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
2edd0 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77  being used by tw
2ede0 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72  o or.** more thr
2edf0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
2ee00 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e   moment in time.
2ee10 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76  .**.** For all v
2ee20 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
2ee30 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c  e up to and incl
2ee40 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20  uding 3.6.23.1, 
2ee50 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  a call to.** [sq
2ee60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77  lite3_reset()] w
2ee70 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65  as required afte
2ee80 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  r sqlite3_step()
2ee90 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69   returned anythi
2eea0 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e  ng.** other than
2eeb0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65   [SQLITE_ROW] be
2eec0 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75  fore any subsequ
2eed0 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ent invocation o
2eee0 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  f.** sqlite3_ste
2eef0 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f  p().  Failure to
2ef00 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61   reset the prepa
2ef10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73  red statement us
2ef20 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2ef30 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20  _reset()] would 
2ef40 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51  result in an [SQ
2ef50 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74  LITE_MISUSE] ret
2ef60 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  urn from.** sqli
2ef70 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74  te3_step().  But
2ef80 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33   after version 3
2ef90 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33  .6.23.1, sqlite3
2efa0 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a  _step() began.**
2efb0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2efc0 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d  3_reset()] autom
2efd0 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73  atically in this
2efe0 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61   circumstance ra
2eff0 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74  ther.** than ret
2f000 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d  urning [SQLITE_M
2f010 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73  ISUSE].  This is
2f020 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20   not considered 
2f030 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a  a compatibility.
2f040 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65  ** break because
2f050 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e   any application
2f060 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69   that ever recei
2f070 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49  ves an SQLITE_MI
2f080 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73  SUSE error.** is
2f090 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e   broken by defin
2f0a0 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c  ition.  The [SQL
2f0b0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53  ITE_OMIT_AUTORES
2f0c0 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ET] compile-time
2f0d0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62   option.** can b
2f0e0 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72  e used to restor
2f0f0 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68  e the legacy beh
2f100 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  avior..**.** <b>
2f110 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20  Goofy Interface 
2f120 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68  Alert:</b> In th
2f130 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2f140 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ce, the sqlite3_
2f150 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c  step().** API al
2f160 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67  ways returns a g
2f170 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64  eneric error cod
2f180 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  e, [SQLITE_ERROR
2f190 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ], following any
2f1a0 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20  .** error other 
2f1b0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  than [SQLITE_BUS
2f1c0 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d  Y] and [SQLITE_M
2f1d0 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73  ISUSE].  You mus
2f1e0 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
2f1f0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2f200 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f210 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ()] in order to 
2f220 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a  find one of the.
2f230 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72  ** specific [err
2f240 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62  or codes] that b
2f250 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20  etter describes 
2f260 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65  the error..** We
2f270 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73   admit that this
2f280 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69   is a goofy desi
2f290 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d  gn.  The problem
2f2a0 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a   has been fixed.
2f2b0 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22  ** with the "v2"
2f2c0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20   interface.  If 
2f2d0 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20  you prepare all 
2f2e0 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74  of your SQL stat
2f2f0 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20  ements.** using 
2f300 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
2f310 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2f320 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f330 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61  e16_v2()] instea
2f340 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61  d.** of the lega
2f350 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  cy [sqlite3_prep
2f360 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2f370 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2f380 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20   interfaces,.** 
2f390 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70  then the more sp
2f3a0 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f  ecific [error co
2f3b0 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65  des] are returne
2f3c0 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79  d directly.** by
2f3d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2f3e0 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65    The use of the
2f3f0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2f400 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  is recommended..
2f410 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2f420 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tep(sqlite3_stmt
2f430 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2f440 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63  REF: Number of c
2f450 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75  olumns in a resu
2f460 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44  lt set.** METHOD
2f470 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2f480 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f490 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2f4a0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2f4b0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f4c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a  columns in the.*
2f4d0 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66  * current row of
2f4e0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2f4f0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2f500 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49  tement] P..** ^I
2f510 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  f prepared state
2f520 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20  ment P does not 
2f530 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61  have results rea
2f540 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  dy to return.** 
2f550 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68  (via calls to th
2f560 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e [sqlite3_colum
2f570 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  n_int | sqlite3_
2f580 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a  column_*()] of.*
2f590 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68  * interfaces) th
2f5a0 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  en sqlite3_data_
2f5b0 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73  count(P) returns
2f5c0 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69   0..** ^The sqli
2f5d0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2f5e0 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72  ) routine also r
2f5f0 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73  eturns 0 if P is
2f600 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2f610 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2f620 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2f630 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2f640 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
2f650 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2f660 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2f670 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44  turned [SQLITE_D
2f680 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  ONE].  ^The sqli
2f690 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2f6a0 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e  ).** will return
2f6b0 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65   non-zero if pre
2f6c0 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73  vious call to [s
2f6d0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2f6e0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2f6f0 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74  ITE_ROW], except
2f700 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20   in the case of 
2f710 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72  the [PRAGMA incr
2f720 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a  emental_vacuum].
2f730 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61  ** where it alwa
2f740 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  ys returns zero 
2f750 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20  since each step 
2f760 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74  of that multi-st
2f770 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74  ep.** pragma ret
2f780 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f  urns 0 columns o
2f790 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65  f data..**.** Se
2f7a0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2f7b0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
2f7c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2f7d0 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74  data_count(sqlit
2f7e0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f7f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f800 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61  : Fundamental Da
2f810 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  tatypes.** KEYWO
2f820 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54  RDS: SQLITE_TEXT
2f830 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76  .**.** ^(Every v
2f840 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68  alue in SQLite h
2f850 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66  as one of five f
2f860 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74  undamental datat
2f870 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ypes:.**.** <ul>
2f880 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2f890 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
2f8a0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45  * <li> 64-bit IE
2f8b0 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  EE floating poin
2f8c0 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e  t number.** <li>
2f8d0 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20   string.** <li> 
2f8e0 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c  BLOB.** <li> NUL
2f8f0 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  L.** </ul>)^.**.
2f900 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2f910 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72  ts are codes for
2f920 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74   each of those t
2f930 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ypes..**.** Note
2f940 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45   that the SQLITE
2f950 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77  _TEXT constant w
2f960 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20  as also used in 
2f970 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2f980 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65  .** for a comple
2f990 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d  tely different m
2f9a0 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72  eaning.  Softwar
2f9b0 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61  e that links aga
2f9c0 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c  inst both.** SQL
2f9d0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e  ite version 2 an
2f9e0 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  d SQLite version
2f9f0 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51   3 should use SQ
2fa00 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a  LITE3_TEXT, not.
2fa10 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a  ** SQLITE_TEXT..
2fa20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
2fa30 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65  E_INTEGER  1.#de
2fa40 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41  fine SQLITE_FLOA
2fa50 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53  T    2.#define S
2fa60 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34  QLITE_BLOB     4
2fa70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2fa80 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65  NULL     5.#ifde
2fa90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20  f SQLITE_TEXT.# 
2faa0 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  undef SQLITE_TEX
2fab0 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  T.#else.# define
2fac0 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20   SQLITE_TEXT    
2fad0 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e   3.#endif.#defin
2fae0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20  e SQLITE3_TEXT  
2faf0 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     3../*.** CAPI
2fb00 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c  3REF: Result Val
2fb10 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79  ues From A Query
2fb20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
2fb30 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
2fb40 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f  ctions}.** METHO
2fb50 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2fb60 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2fb70 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
2fb80 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
2fb90 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
2fba0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
2fbb0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
2fbc0 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
2fbd0 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
2fbe0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
2fbf0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
2fc00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2fc10 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
2fc20 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
2fc30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2fc40 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
2fc50 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
2fc60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2fc70 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
2fc80 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
2fc90 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
2fca0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2fcb0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
2fcc0 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
2fcd0 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
2fce0 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
2fcf0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2fd00 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2fd10 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
2fd20 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
2fd30 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2fd40 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2fd50 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
2fd60 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
2fd70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2fd80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
2fd90 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2fda0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
2fdb0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
2fdc0 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
2fdd0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
2fde0 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
2fdf0 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
2fe00 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2fe10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2fe20 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
2fe30 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
2fe40 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
2fe50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2fe60 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
2fe70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
2fe80 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
2fe90 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
2fea0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2feb0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
2fec0 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
2fed0 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
2fee0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2fef0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
2ff00 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
2ff10 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
2ff20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ff30 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
2ff40 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2ff50 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
2ff60 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
2ff70 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
2ff80 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2ff90 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
2ffa0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
2ffb0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
2ffc0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ffd0 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
2ffe0 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
2fff0 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
30000 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
30010 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
30020 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
30030 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
30040 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
30050 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30060 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
30070 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
30080 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
30090 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
300a0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
300b0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
300c0 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
300d0 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
300e0 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
300f0 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
30100 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
30110 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
30120 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
30130 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
30140 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
30150 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
30160 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30170 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
30180 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
30190 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
301a0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
301b0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
301c0 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
301d0 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
301e0 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
301f0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
30200 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30210 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
30220 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
30230 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
30240 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
30250 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
30260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
30270 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
30280 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
30290 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
302a0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
302b0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
302c0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
302d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
302e0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
302f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
30300 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
30310 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
30320 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
30330 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
30340 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
30350 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30360 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
30370 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
30380 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
30390 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
303a0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
303b0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
303c0 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
303d0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
303e0 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
303f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
30400 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
30410 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
30420 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
30430 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
30440 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
30450 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
30460 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
30470 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
30480 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
30490 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
304a0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
304b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
304c0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
304d0 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
304e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
304f0 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
30500 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
30510 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
30520 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
30530 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
30540 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
30550 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
30560 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
30570 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
30580 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
30590 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
305a0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
305b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
305c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
305d0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
305e0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
305f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30600 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
30610 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
30620 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
30630 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
30640 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
30650 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
30660 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30670 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
30680 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
30690 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
306a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
306b0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
306c0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
306d0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
306e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
306f0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
30700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30710 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
30720 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
30730 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
30740 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
30750 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
30760 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
30770 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
30780 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
30790 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
307a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
307b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
307c0 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
307d0 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
307e0 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
307f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
30800 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
30810 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
30820 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30830 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
30840 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30850 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
30860 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
30870 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
30880 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
30890 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
308a0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
308b0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
308c0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
308d0 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
308e0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61  ter..**.** <b>Wa
308f0 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20  rning:</b> ^The 
30900 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
30910 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
30920 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
30930 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
30940 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
30950 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d   object.  In a m
30960 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76  ultithreaded env
30970 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20  ironment,.** an 
30980 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30990 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
309a0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
309b0 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a  d safely with.**
309c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
309d0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
309e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
309f0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
30a00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30a10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30a20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
30a30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30a40 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
30a50 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
30a60 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
30a70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
30a80 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30a90 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
30aa0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30ab0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30ad0 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76  es()], the behav
30ae0 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61  ior is not threa
30af0 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dsafe..**.** The
30b00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
30b10 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
30b20 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
30b30 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
30b40 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
30b50 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
30b60 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
30b70 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
30b80 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
30b90 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
30ba0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
30bb0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
30bc0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
30bd0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
30be0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
30bf0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
30c00 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
30c10 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
30c20 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
30c30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
30c40 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
30c50 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
30c60 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
30c70 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
30c80 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
30c90 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
30ca0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
30cb0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
30cc0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
30cd0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
30ce0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
30cf0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30d00 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
30d10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30d20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30d30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30d40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
30d50 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
30d60 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
30d70 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
30d80 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30d90 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
30da0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
30db0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
30dc0 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
30dd0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
30de0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
30df0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
30e00 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
30e10 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
30e20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30e30 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
30e40 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
30e50 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
30e60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
30e70 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
30e80 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
30e90 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
30ea0 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
30eb0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30ec0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
30ed0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
30ee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
30ef0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
30f00 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
30f10 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
30f20 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
30f30 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
30f40 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
30f50 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
30f60 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
30f70 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
30f80 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
30f90 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
30fa0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
30fb0 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
30fc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
30fd0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30fe0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30ff0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
31000 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
31010 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
31020 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
31030 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
31040 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
31050 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
31060 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
31070 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
31080 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
31090 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
310a0 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
310b0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
310c0 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
310d0 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
310e0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
310f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31100 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
31110 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
31120 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
31130 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
31140 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
31150 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
31160 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
31170 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
31180 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
31190 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
311a0 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
311b0 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
311c0 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
311d0 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
311e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
311f0 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
31200 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31210 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
31220 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
31230 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
31240 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
31250 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
31260 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
31270 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31280 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
31290 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
312a0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
312b0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
312c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
312d0 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
312e0 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
312f0 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
31300 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
31310 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
31320 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
31330 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
31340 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31350 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
31360 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
31370 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
31380 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
31390 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
313a0 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
313b0 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
313c0 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
313d0 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
313e0 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
313f0 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
31400 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
31410 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
31420 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
31430 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
31440 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
31450 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
31460 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
31470 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
31480 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
31490 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
314a0 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
314b0 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
314c0 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
314d0 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
314e0 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
314f0 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
31500 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
31510 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
31520 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
31530 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
31540 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
31550 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
31560 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
31570 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
31580 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
31590 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
315a0 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
315b0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
315c0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
315d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
315e0 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
315f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31600 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
31610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31620 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
31630 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
31640 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
31650 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
31660 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
31670 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
31680 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
31690 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
316a0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
316b0 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
316c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
316d0 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
316e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
316f0 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
31700 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
31710 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
31720 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
31730 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31740 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
31750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31760 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
31770 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
31780 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
31790 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
317a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
317b0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
317c0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
317d0 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
317e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
317f0 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
31800 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
31810 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
31820 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
31830 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
31840 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31850 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
31860 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
31870 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
31880 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
31890 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
318a0 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
318b0 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
318c0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
318d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
318e0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
318f0 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
31900 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
31910 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
31920 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
31930 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
31940 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
31950 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  .  Do <em>not</e
31960 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e  m> pass the poin
31970 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ters returned.**
31980 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
31990 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
319a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
319b0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
319c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
319d0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
319e0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
319f0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
31a00 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
31a10 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
31a20 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
31a30 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
31a40 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
31a50 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
31a60 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
31a70 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
31a80 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
31a90 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
31aa0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
31ab0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
31ac0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
31ad0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
31ae0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
31af0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
31b00 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  .*/.const void *
31b10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31b20 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
31b30 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
31b40 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
31b50 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
31b60 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31b70 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
31b80 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
31b90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31ba0 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c  Col);.double sql
31bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
31bc0 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
31bd0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
31be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31bf0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
31c00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
31c10 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
31c20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
31c30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31c40 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
31c50 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
31c60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31c70 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ext(sqlite3_stmt
31c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
31c90 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31ca0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
31cb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31cc0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
31cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31ce0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31cf0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
31d00 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
31d10 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
31d20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31d30 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
31d40 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
31d50 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
31d60 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
31d70 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71  * DESTRUCTOR: sq
31d80 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31d90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
31da0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
31db0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
31dc0 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
31dd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
31de0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31df0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
31e00 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
31e10 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
31e20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
31e30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31e40 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
31e50 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
31e60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
31e70 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
31e80 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
31e90 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
31ea0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
31eb0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
31ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
31ed0 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
31ee0 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
31ef0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
31f00 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
31f10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31f20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
31f30 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
31f40 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
31f50 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
31f60 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
31f70 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
31f80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
31f90 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
31fa0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
31fb0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
31fc0 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
31fd0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
31fe0 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
31ff0 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
32000 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
32010 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
32020 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
32030 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
32040 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
32050 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
32060 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
32070 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
32080 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
32090 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
320a0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
320b0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
320c0 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
320d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
320e0 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
320f0 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
32100 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
32110 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
32120 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
32130 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
32140 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
32150 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
32160 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
32170 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
32180 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
32190 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
321a0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
321b0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
321c0 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
321d0 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
321e0 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
321f0 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
32200 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
32210 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
32220 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
32230 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
32240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32250 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
32260 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
32270 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
32280 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
32290 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
322a0 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
322b0 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
322c0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
322d0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
322e0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
322f0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
32300 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
32310 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
32320 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
32330 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
32340 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
32350 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
32360 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
32370 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
32380 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
32390 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
323a0 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
323b0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
323c0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
323d0 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
323e0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
323f0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
32400 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
32410 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
32420 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
32430 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
32440 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
32450 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
32460 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
32470 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
32480 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
32490 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
324a0 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
324b0 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
324c0 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
324d0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
324e0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
324f0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
32500 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
32510 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32520 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
32530 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
32540 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
32550 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
32560 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
32570 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
32580 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
32590 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
325a0 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
325b0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
325c0 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
325d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
325e0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
325f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
32600 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
32610 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
32620 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
32630 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
32640 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
32650 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
32660 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
32670 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
32680 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
32690 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
326a0 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
326b0 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
326c0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
326d0 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
326e0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
326f0 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
32700 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
32710 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
32720 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
32730 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
32740 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
32750 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ns}.** METHOD: s
32760 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
32770 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
32780 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
32790 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
327a0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
327b0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
327c0 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
327d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
327e0 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
327f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
32800 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
32810 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
32820 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
32830 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
32840 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
32850 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
32860 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
32870 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
32880 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
32890 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
328a0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
328b0 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
328c0 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
328d0 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
328e0 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
328f0 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
32900 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32910 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
32920 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
32930 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
32940 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32950 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
32960 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
32970 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
32980 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
32990 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
329a0 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
329b0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
329c0 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
329d0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
329e0 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
329f0 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
32a00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32a10 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
32a20 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
32a30 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
32a40 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
32a50 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32a60 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
32a70 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
32a80 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
32a90 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
32aa0 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
32ab0 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
32ac0 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
32ad0 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
32ae0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
32af0 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
32b00 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
32b10 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
32b20 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
32b30 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
32b40 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
32b50 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
32b60 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
32b70 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
32b80 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
32b90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
32ba0 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
32bb0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
32bc0 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
32bd0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
32be0 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
32bf0 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
32c00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
32c10 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
32c20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
32c30 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
32c40 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
32c50 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
32c60 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
32c70 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
32c80 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
32c90 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
32ca0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
32cb0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
32cc0 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
32cd0 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
32ce0 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
32cf0 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
32d00 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
32d10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
32d20 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
32d30 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
32d40 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
32d50 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
32d60 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
32d70 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
32d80 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
32d90 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
32da0 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
32db0 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
32dc0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
32dd0 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
32de0 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
32df0 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
32e00 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
32e10 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
32e20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
32e30 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
32e40 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
32e50 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
32e60 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
32e70 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
32e80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32e90 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
32ea0 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
32eb0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
32ec0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32ed0 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
32ee0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
32ef0 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
32f00 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
32f10 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
32f20 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
32f30 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
32f40 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
32f50 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
32f60 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
32f70 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
32f80 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
32f90 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
32fa0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
32fb0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32fc0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
32fd0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
32fe0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
32ff0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
33000 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
33010 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
33020 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
33030 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
33040 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
33050 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
33060 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
33070 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
33080 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
33090 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
330a0 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
330b0 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
330c0 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
330d0 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
330e0 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
330f0 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
33100 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
33110 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
33120 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
33130 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
33140 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
33150 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
33160 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
33170 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
33180 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
33190 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
331a0 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
331b0 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
331c0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
331d0 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
331e0 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
331f0 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
33200 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
33210 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
33220 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
33230 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
33240 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
33250 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
33260 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
33270 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
33280 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
33290 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
332a0 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
332b0 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
332c0 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
332d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
332e0 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
332f0 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
33300 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
33310 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
33320 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
33330 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
33340 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
33350 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
33360 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
33370 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
33380 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
33390 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
333a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
333b0 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
333c0 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
333d0 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
333e0 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
333f0 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
33400 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
33410 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
33420 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
33430 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
33440 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
33450 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
33460 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
33470 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
33480 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
33490 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
334a0 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
334b0 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
334c0 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
334d0 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
334e0 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
334f0 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
33500 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33510 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33520 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
33530 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
33540 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
33550 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
33560 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
33570 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
33580 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
33590 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
335a0 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
335b0 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
335c0 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
335d0 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
335e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
335f0 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
33600 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
33610 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
33620 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
33630 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33640 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
33650 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
33660 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
33670 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
33680 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
33690 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
336a0 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
336b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
336c0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
336d0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
336e0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
336f0 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
33700 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33710 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33720 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
33730 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
33740 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
33750 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
33760 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
33770 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
33780 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
33790 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
337a0 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
337b0 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
337c0 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
337d0 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
337e0 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
337f0 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
33800 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
33810 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
33820 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
33830 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
33840 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
33850 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
33860 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
33870 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
33880 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
33890 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
338a0 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
338b0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
338c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
338d0 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
338e0 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
338f0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
33900 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
33910 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
33920 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
33930 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
33940 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
33950 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
33960 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
33970 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
33980 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
33990 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
339a0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
339b0 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
339c0 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
339d0 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
339e0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
339f0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
33a00 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
33a10 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
33a20 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
33a30 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
33a40 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
33a50 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
33a60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33a70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
33a80 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
33a90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33aa0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
33ab0 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
33ac0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
33ad0 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
33ae0 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
33af0 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
33b00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
33b10 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
33b20 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
33b30 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
33b40 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
33b50 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
33b60 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
33b70 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33b80 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
33b90 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
33ba0 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
33bb0 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33bc0 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33bd0 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33be0 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33bf0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33c00 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33c10 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33c20 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33c30 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33c40 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33c50 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
33c60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
33c70 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
33c80 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33c90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
33ca0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
33cb0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
33cc0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
33cd0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33ce0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33cf0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33d00 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33d10 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33d20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33d30 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33d40 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33d50 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
33d60 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
33d70 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
33d80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33d90 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
33da0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
33db0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
33dc0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
33dd0 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
33de0 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
33df0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
33e00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33e10 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33e20 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
33e30 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
33e40 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33e50 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33e60 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
33e70 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33e80 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
33e90 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
33ea0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33eb0 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
33ec0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33ed0 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
33ee0 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
33ef0 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
33f00 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
33f10 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
33f20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
33f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33f40 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20 20  8           1   
33f50 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31 34   /* IMP: R-37514
33f60 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69 6e  -35566 */.#defin
33f70 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
33f80 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a 20          2    /* 
33f90 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37 36  IMP: R-03371-376
33fa0 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  37 */.#define SQ
33fb0 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
33fc0 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50 3a      3    /* IMP:
33fd0 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20 2a   R-51971-34154 *
33fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33ff0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
34000 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
34010 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
34020 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34030 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
34040 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65      /* Deprecate
34050 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
34060 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34070 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74  D  8    /* sqlit
34080 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34090 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a  ion only */../*.
340a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
340b0 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a  ction Flags.**.*
340c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
340d0 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f  s may be ORed to
340e0 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65 20  gether with the 
340f0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
34100 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65 78   | preferred tex
34110 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74  t encoding] as t
34120 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
34130 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  nt.** to [sqlite
34140 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34150 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  n()], [sqlite3_c
34160 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
34170 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
34180 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34190 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64  ion_v2()]..*/.#d
341a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
341b0 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78  ERMINISTIC    0x
341c0 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
341d0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
341e0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50  Functions.** DEP
341f0 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
34200 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ese functions ar
34210 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20  e [deprecated]. 
34220 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69   In order to mai
34230 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72  ntain.** backwar
34240 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
34250 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65   with older code
34260 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  , these function
34270 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74  s continue .** t
34280 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20  o be supported. 
34290 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70   However, new ap
342a0 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
342b0 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75  d avoid.** the u
342c0 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63  se of these func
342d0 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f 75  tions.  To encou
342e0 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72 73  rage programmers
342f0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65   to avoid.** the
34300 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
34310 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61 69   will not explai
34320 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  n what they do..
34330 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
34340 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
34350 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
34360 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
34370 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
34380 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34390 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
343a0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
343b0 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
343c0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
343d0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
343e0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
343f0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
34400 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
34410 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
34420 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
34430 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
34440 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
34450 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
34460 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
34470 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
34480 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
34490 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
344a0 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
344b0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
344c0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
344d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
344e0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
344f0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
34500 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34510 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
34520 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
34530 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
34540 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
34550 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
34560 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
34570 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
34580 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
34590 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
345a0 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
345b0 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
345c0 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
345d0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
345e0 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a  aggregate.  .**.
345f0 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
34600 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
34610 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
34620 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
34630 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
34640 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34650 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
34660 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34670 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
34680 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
34690 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
346a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
346b0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
346c0 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
346d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
346e0 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
346f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
34700 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
34710 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34720 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
34730 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
34740 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34750 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
34760 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
34770 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
34780 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
34790 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
347a0 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
347b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
347c0 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
347d0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
347e0 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
347f0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34800 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
34810 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
34820 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
34830 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
34840 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34850 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
34860 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
34870 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
34880 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
34890 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
348a0 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
348b0 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
348c0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
348d0 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
348e0 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
348f0 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
34900 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34910 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
34920 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
34930 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
34940 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
34950 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
34960 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
34970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34980 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
34990 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
349a0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
349b0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
349c0 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
349d0 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
349e0 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
349f0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34a00 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
34a10 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
34a20 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
34a30 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
34a40 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
34a50 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
34a60 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
34a70 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
34a80 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34a90 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
34aa0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
34ab0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
34ac0 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
34ad0 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
34ae0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
34af0 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
34b00 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
34b10 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
34b20 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
34b30 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
34b40 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
34b50 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
34b60 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
34b70 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
34b80 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
34b90 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
34ba0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
34bb0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
34bc0 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
34bd0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
34be0 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
34bf0 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
34c00 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
34c10 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
34c20 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
34c30 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
34c40 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
34c50 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
34c60 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
34c70 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
34c80 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
34c90 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
34ca0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
34cb0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
34cc0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
34cd0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
34ce0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
34cf0 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
34d00 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
34d10 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
34d20 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
34d30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
34d40 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
34d50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34d60 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
34d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34d80 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
34d90 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
34da0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34db0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34dc0 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
34dd0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
34de0 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
34df0 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
34e00 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
34e10 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
34e20 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
34e30 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
34e40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34e50 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
34e60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
34e70 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
34e80 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
34e90 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
34ea0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
34eb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
34ec0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
34ed0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34ee0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
34ef0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
34f00 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
34f10 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
34f20 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
34f30 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
34f40 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
34f50 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34f60 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
34f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34f80 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34f90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34fa0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
34fb0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
34fc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34fd0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
34fe0 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
34ff0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
35000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35010 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
35020 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
35030 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35040 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35050 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62   Finding The Sub
35060 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75  type Of SQL Valu
35070 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
35080 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
35090 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
350a0 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66  lue_subtype(V) f
350b0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
350c0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a  the subtype for.
350d0 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69  ** an [applicati
350e0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
350f0 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e  unction] argumen
35100 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70  t V.  The subtyp
35110 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
35120 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
35130 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61  pass a limited a
35140 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74  mount of context
35150 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c   from.** one SQL
35160 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f   function to ano
35170 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b  ther.  Use the [
35180 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73  sqlite3_result_s
35190 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75  ubtype()].** rou
351a0 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20  tine to set the 
351b0 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20  subtype for the 
351c0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
351d0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  an SQL function.
351e0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
351f0 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75  kes no use of su
35200 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49  btype itself.  I
35210 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20  t merely passes 
35220 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66  the subtype.** f
35230 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f  rom the result o
35240 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69  f one [applicati
35250 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
35260 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68  unction] into th
35270 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e  e.** input of an
35280 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e  other..*/.unsign
35290 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  ed int sqlite3_v
352a0 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71 6c  alue_subtype(sql
352b0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
352c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
352d0 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c  opy And Free SQL
352e0 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
352f0 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
35300 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35310 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29  te3_value_dup(V)
35320 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
35330 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
35340 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
35350 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72  * object D and r
35360 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
35370 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20   to that copy.  
35380 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  ^The [sqlite3_va
35390 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a  lue] returned.**
353a0 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64   is a [protected
353b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
353c0 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74  object even if t
353d0 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e  he input is not.
353e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
353f0 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
35400 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
35410 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c  NULL if V is NUL
35420 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d  L or if a.** mem
35430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
35440 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ails..**.** ^The
35450 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
35460 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63 65  ree(V) interface
35470 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74   frees an [sqlit
35480 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35490 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
354a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
354b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
354c0 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20  )].  ^If V is a 
354d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
354e0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  then sqlite3_val
354f0 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61 20  ue_free(V) is a 
35500 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
35510 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  */.sqlite3_value
35520 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
35530 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65  dup(const sqlite
35540 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20  3_value*);.void 
35550 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72  sqlite3_value_fr
35560 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ee(sqlite3_value
35570 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35580 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
35590 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
355a0 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f 44  ontext.** METHOD
355b0 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
355c0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
355d0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
355e0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
355f0 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
35600 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
35610 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
35620 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
35630 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
35640 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
35650 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35660 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
35670 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
35680 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
35690 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
356a0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
356b0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
356c0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
356d0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
356e0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
356f0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
35700 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
35710 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
35720 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
35730 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
35740 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
35750 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
35760 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35770 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
35780 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
35790 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
357a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
357b0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
357c0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
357d0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
357e0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
357f0 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
35800 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
35810 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
35820 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
35830 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
35840 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
35850 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
35860 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
35870 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
35880 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35890 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
358a0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
358b0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
358c0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
358d0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
358e0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
358f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35900 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
35910 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
35920 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
35930 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
35940 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
35950 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
35960 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
35970 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
35980 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35990 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73 74  r .** when first
359a0 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73 20   called if N is 
359b0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
359c0 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66  al to zero or if
359d0 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c   a memory.** all
359e0 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75  ocate error occu
359f0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  rs..**.** ^(The 
35a00 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20  amount of space 
35a10 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c  allocated by sql
35a20 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35a30 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a  ontext(C,N) is.*
35a40 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20  * determined by 
35a50 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
35a60 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73 73  on first success
35a70 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67  ful call.  Chang
35a80 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65  ing the.** value
35a90 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75   of N in subsequ
35aa0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
35ab0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35ac0 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a  ntext() within.*
35ad0 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  * the same aggre
35ae0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
35af0 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20  stance will not 
35b00 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  resize the memor
35b10 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e  y.** allocation.
35b20 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20 78  )^  Within the x
35b30 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c 20  Final callback, 
35b40 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79 20  it is customary 
35b50 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e  to set.** N=0 in
35b60 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
35b70 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35b80 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61 74  ext(C,N) so that
35b90 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73   no .** pointles
35ba0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
35bb0 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a  ions occur..**.*
35bc0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
35bd0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
35be0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
35bf0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
35c00 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35c10 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
35c20 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
35c30 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
35c40 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
35c50 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
35c60 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
35c70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
35c80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
35c90 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
35ca0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
35cb0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
35cc0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
35cd0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
35ce0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
35cf0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
35d00 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
35d10 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
35d20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35d30 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35d40 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
35d50 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
35d60 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35d70 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
35d80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35d90 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
35da0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
35db0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
35dc0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
35dd0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
35de0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35df0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
35e00 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
35e10 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
35e20 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
35e30 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
35e40 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
35e50 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
35e60 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
35e70 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
35e80 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35e90 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
35ea0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
35eb0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
35ec0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
35ed0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
35ee0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
35ef0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
35f00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35f10 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
35f20 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
35f30 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
35f40 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
35f50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35f60 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
35f70 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f  s running..*/.vo
35f80 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72  id *sqlite3_user
35f90 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  _data(sqlite3_co
35fa0 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
35fb0 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
35fc0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f  se Connection Fo
35fd0 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  r Functions.** M
35fe0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
35ff0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  ontext.**.** ^Th
36000 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
36010 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
36020 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36030 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
36040 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36050 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36060 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
36070 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
36080 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
36090 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
360a0 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
360b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
360c0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
360d0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
360e0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
360f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
36100 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
36110 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
36120 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
36130 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  dle(sqlite3_cont
36140 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
36150 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e  PI3REF: Function
36160 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a   Auxiliary Data.
36170 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36180 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
36190 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
361a0 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
361b0 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29 20  (non-aggregate) 
361c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
361d0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
361e0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
361f0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
36200 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
36210 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
36220 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
36230 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
36240 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
36250 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
36260 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
36270 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
36280 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
36290 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
362a0 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20 65  preserved.  An e
362b0 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68 65  xample.** of whe
362c0 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62 65  re this might be
362d0 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61 20   useful is in a 
362e0 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73 69  regular-expressi
362f0 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20 66  on matching.** f
36300 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
36310 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
36320 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
36330 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 73  ression can be s
36340 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
36350 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
36360 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72 6e  with the pattern
36370 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54 68   string.  .** Th
36380 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  en as long as th
36390 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
363a0 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61 6d   remains the sam
363b0 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69 6c  e,.** the compil
363c0 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  ed regular expre
363d0 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75  ssion can be reu
363e0 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a  sed on multiple.
363f0 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
36400 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
36410 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
36420 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
36430 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
36440 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
36450 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
36460 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
36470 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
36480 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
36490 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
364a0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
364b0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
364c0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
364d0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74 68  function. ^If th
364e0 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64 61  ere is no metada
364f0 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
36500 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74 69   with the functi
36510 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68 69  on argument, thi
36520 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  s sqlite3_get_au
36530 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
36540 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 4e  e.** returns a N
36550 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
36560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36570 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36580 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20 73  P,X) interface s
36590 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64 61  aves P as metada
365a0 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a  ta for the N-th.
365b0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  ** argument of t
365c0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
365d0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
365e0 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a    ^Subsequent.**
365f0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36600 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_get_auxdata(C,
36610 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f 6d  N) return P from
36620 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
36630 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  .** sqlite3_set_
36640 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
36650 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65 74   call if the met
36660 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20 76  adata is still v
36670 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20  alid or.** NULL 
36680 69 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  if the metadata 
36690 68 61 73 20 62 65 65 6e 20 64 69 73 63 61 72 64  has been discard
366a0 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20 65 61  ed..** ^After ea
366b0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
366c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
366d0 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20 58 20  ,N,P,X) where X 
366e0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
366f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f  SQLite will invo
36700 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ke the destructo
36710 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77 69 74  r function X wit
36720 68 20 70 61 72 61 6d 65 74 65 72 20 50 20 65 78  h parameter P ex
36730 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77  actly.** once, w
36740 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61 74 61  hen the metadata
36750 20 69 73 20 64 69 73 63 61 72 64 65 64 2e 0a 2a   is discarded..*
36760 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
36770 20 74 6f 20 64 69 73 63 61 72 64 20 74 68 65 20   to discard the 
36780 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e 79 20  metadata at any 
36790 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e 67 3a  time, including:
367a0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68   <ul>.** <li> wh
367b0 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
367c0 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61  ding function pa
367d0 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 2c  rameter changes,
367e0 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e   or.** <li> when
367f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36800 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
36810 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
36820 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
36830 20 20 20 20 20 53 51 4c 20 73 74 61 74 65 6d 65       SQL stateme
36840 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77  nt, or.** <li> w
36850 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  hen sqlite3_set_
36860 61 75 78 64 61 74 61 28 29 20 69 73 20 69 6e 76  auxdata() is inv
36870 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  oked again on th
36880 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74 65 72  e same parameter
36890 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72  , or.** <li> dur
368a0 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ing the original
368b0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
368c0 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68 65 6e  data() call when
368d0 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20 20 20   a memory .**   
368e0 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72     allocation er
368f0 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f 75 6c  ror occurs. </ul
36900 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  >)^.**.** Note t
36910 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74 20 69  he last bullet i
36920 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20 20 54  n particular.  T
36930 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 58 20  he destructor X 
36940 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  in .** sqlite3_s
36950 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
36960 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  ,X) might be cal
36970 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  led immediately,
36980 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a 20 73   before the.** s
36990 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
369a0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 65  ta() interface e
369b0 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20 48 65  ven returns.  He
369c0 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  nce sqlite3_set_
369d0 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73 68 6f  auxdata().** sho
369e0 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20 6e 65  uld be called ne
369f0 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  ar the end of th
36a00 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
36a10 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 74 68  mentation and th
36a20 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6d  e.** function im
36a30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
36a40 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61 6e 79  uld not make any
36a50 20 75 73 65 20 6f 66 20 50 20 61 66 74 65 72 0a   use of P after.
36a60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
36a70 75 78 64 61 74 61 28 29 20 68 61 73 20 62 65 65  uxdata() has bee
36a80 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n called..**.** 
36a90 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
36aa0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
36ab0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
36ac0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
36ad0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
36ae0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
36af0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
36b00 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64 69 6e  stants, includin
36b10 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c  g literal.** val
36b20 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74  ues and [paramet
36b30 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65 73 73  ers] and express
36b40 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20 66 72  ions composed fr
36b50 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e 0a 2a  om the same.)^.*
36b60 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36b70 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
36b80 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
36b90 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
36ba0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
36bb0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
36bc0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
36bd0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
36be0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
36bf0 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73 71 6c  int N);.void sql
36c00 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36c10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
36c20 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c  *, int N, void*,
36c30 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64 2a 29   void (*)(void*)
36c40 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  );.../*.** CAPI3
36c50 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44  REF: Constants D
36c60 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61 6c 20  efining Special 
36c70 44 65 73 74 72 75 63 74 6f 72 20 42 65 68 61 76  Destructor Behav
36c80 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ior.**.** These 
36c90 61 72 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  are special valu
36ca0 65 73 20 66 6f 72 20 74 68 65 20 64 65 73 74 72  es for the destr
36cb0 75 63 74 6f 72 20 74 68 61 74 20 69 73 20 70 61  uctor that is pa
36cc0 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
36cd0 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74  * final argument
36ce0 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
36cf0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
36d00 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20  t_blob()].  ^If 
36d10 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a  the destructor.*
36d20 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 53 51  * argument is SQ
36d30 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69 74 20  LITE_STATIC, it 
36d40 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
36d50 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72 20 69  ontent pointer i
36d60 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e  s constant.** an
36d70 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63 68 61  d will never cha
36d80 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f  nge.  It does no
36d90 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64 65 73  t need to be des
36da0 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a  troyed.  ^The.**
36db0 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
36dc0 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20 74 68  T value means th
36dd0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 77  at the content w
36de0 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67  ill likely chang
36df0 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72  e in.** the near
36e00 20 66 75 74 75 72 65 20 61 6e 64 20 74 68 61 74   future and that
36e10 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d   SQLite should m
36e20 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72 69 76  ake its own priv
36e30 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  ate copy of.** t
36e40 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72  he content befor
36e50 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
36e60 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66 20 69  ** The typedef i
36e70 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 77  s necessary to w
36e80 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c  ork around probl
36e90 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a  ems in certain.*
36ea0 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e  * C++ compilers.
36eb0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
36ec0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
36ed0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
36ee0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
36ef0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
36f00 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
36f10 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
36f20 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
36f30 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
36f40 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
36f50 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
36f60 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
36f70 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
36f80 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d  QL Function.** M
36f90 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63  ETHOD: sqlite3_c
36fa0 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65  ontext.**.** The
36fb0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
36fc0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
36fd0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
36fe0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
36ff0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
37000 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
37010 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
37020 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37030 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
37040 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37050 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
37060 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
37070 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
37080 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
37090 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
370a0 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
370b0 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
370c0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
370d0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
370e0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
370f0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
37100 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
37110 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
37120 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
37130 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
37140 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
37150 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
37160 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37170 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
37180 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37190 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
371a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
371b0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
371c0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
371d0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
371e0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
371f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
37200 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
37210 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
37220 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
37230 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
37240 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37250 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
37260 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e 64 20 73  oblob(C,N) and s
37270 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
37280 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29 0a 2a 2a  roblob64(C,N).**
37290 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
372a0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
372b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
372c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
372d0 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f 42 20 63  o be.** a BLOB c
372e0 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
372f0 72 6f 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62  ro bytes and N b
37300 79 74 65 73 20 69 6e 20 73 69 7a 65 2e 0a 2a 2a  ytes in size..**
37310 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37320 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
37330 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37340 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
37350 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
37360 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37370 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
37380 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
37390 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
373a0 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
373b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
373c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
373d0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
373e0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
373f0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
37400 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
37410 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
37420 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
37430 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
37440 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
37450 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
37460 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
37470 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
37480 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
37490 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
374a0 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
374b0 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
374c0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
374d0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
374e0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
374f0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
37500 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
37510 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
37520 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
37530 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37540 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
37550 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37560 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
37570 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
37580 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
37590 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
375a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
375b0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
375c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
375d0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
375e0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
375f0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
37600 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
37610 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
37620 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
37630 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
37640 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
37650 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37660 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37670 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
37680 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37690 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
376a0 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
376b0 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
376c0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
376d0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
376e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
376f0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
37700 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
37710 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37720 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
37730 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
37740 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
37750 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
37760 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
37770 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
37780 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
37790 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
377a0 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
377b0 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
377c0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
377d0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
377e0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
377f0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
37800 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37810 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
37820 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
37830 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
37840 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
37850 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
37860 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
37870 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
37880 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
37890 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
378a0 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
378b0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
378c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
378d0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
378e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
378f0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
37900 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
37910 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
37920 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37930 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
37940 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
37950 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
37960 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
37970 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
37980 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
37990 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
379a0 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
379b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
379c0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
379d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
379e0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
379f0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
37a00 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
37a10 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
37a20 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
37a30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37a40 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
37a50 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
37a60 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
37a70 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
37a80 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37a90 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
37aa0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
37ab0 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
37ac0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
37ad0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
37ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37af0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
37b00 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
37b10 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
37b20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37b30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37b40 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
37b50 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
37b60 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
37b70 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
37b80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37b90 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
37ba0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
37bb0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37bc0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
37bd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37be0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
37bf0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
37c00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37c10 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
37c20 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
37c30 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
37c40 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
37c50 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37c60 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
37c70 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
37c80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
37c90 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
37ca0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37cb0 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
37cc0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
37cd0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
37ce0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
37cf0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
37d00 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
37d10 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
37d20 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
37d30 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
37d40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37d50 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28 29 20  result_text64() 
37d60 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
37d70 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
37d80 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69 63 61  of an.** applica
37d90 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37da0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 74 65  ction to be a te
37db0 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61 6e 20  xt string in an 
37dc0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70 65 63  encoding.** spec
37dd0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 66  ified by the fif
37de0 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20 70 61  th (and last) pa
37df0 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20 6d  rameter, which m
37e00 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20 6f 66  ust be one.** of
37e10 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
37e20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
37e30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
37e40 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
37e50 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c 69 74  16LE]..** ^SQLit
37e60 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
37e70 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
37e80 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
37e90 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
37ea0 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
37eb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37ec0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
37ed0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
37ee0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37ef0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37f00 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
37f10 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
37f20 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
37f30 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
37f40 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
37f50 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
37f60 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
37f70 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
37f80 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
37f90 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
37fa0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
37fb0 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
37fc0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
37fd0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
37fe0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
37ff0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
38000 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
38010 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
38020 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
38030 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
38040 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
38050 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
38060 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
38070 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
38080 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
38090 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
380a0 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
380b0 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
380c0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
380d0 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
380e0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
380f0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
38100 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
38110 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
38120 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
38130 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
38140 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
38150 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
38160 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
38170 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
38180 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
38190 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
381a0 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
381b0 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
381c0 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
381d0 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
381e0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
381f0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
38200 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
38210 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
38220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
38230 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
38240 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
38250 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
38260 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
38270 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
38280 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
38290 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
382a0 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
382b0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
382c0 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
382d0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
382e0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
382f0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
38300 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
38310 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
38320 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
38330 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
38340 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
38350 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
38360 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
38370 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
38380 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
38390 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
383a0 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
383b0 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
383c0 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
383d0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
383e0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
383f0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
38400 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
38410 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
38420 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
38430 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
38440 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
38450 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
38460 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
38470 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
38480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38490 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
384a0 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
384b0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
384c0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
384d0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
384e0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
384f0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
38500 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
38510 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
38520 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
38530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
38540 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
38550 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
38560 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
38570 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38580 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38590 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 6f  n to be a copy o
385a0 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  f the.** [unprot
385b0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
385c0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
385d0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
385e0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
385f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
38600 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
38610 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
38620 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
38630 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
38640 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
38650 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
38660 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
38670 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
38680 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
38690 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
386a0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
386b0 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
386c0 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
386d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
386e0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
386f0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
38700 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
38710 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
38720 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
38730 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
38740 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
38750 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
38760 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
38770 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
38780 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
38790 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
387a0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
387b0 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
387c0 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
387d0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
387e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
387f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38800 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
38810 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
38820 7