/ Hex Artifact Content
Login

Artifact f18858fc9440fd3c399b733057d12c53a2360d11:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6380: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6390: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
63a0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
63b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
63c0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
63d0: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63e0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63f0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
6400: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6410: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
6420: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
6430: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6440: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6450: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6460: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6470: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6480: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6490: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
64a0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
64b0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
64c0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
64d0: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
6500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
6510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
6520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
6530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
65a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
65b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
65c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
65d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
6610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
6620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
6630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
66b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
66c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
66d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
6700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
6710: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
6720: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6730: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6740: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6750: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6760: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6770: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6780: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6790: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
67a0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
67b0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
67c0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
67d0: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67e0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67f0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
6800: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
6810: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
6820: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
6830: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6850: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6860: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6870: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6880: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6890: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
68a0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
68b0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
68c0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
68d0: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68e0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68f0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
6900: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
6910: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
6920: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
6930: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6940: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6950: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6960: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6970: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6980: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6990: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
69a0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6ab0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6b10: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6b20: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b80: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b90: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6bb0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6bc0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bf0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6c00: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6c20: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6c30: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c50: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c60: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c70: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c90: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6ca0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6cb0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6cc0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6cd0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ce0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cf0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6d00: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6d10: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6d20: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6d30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d40: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d50: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d60: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d70: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d90: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6da0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6db0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6dc0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6dd0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6de0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6df0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6e00: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6e10: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6e20: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6e30: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e40: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e50: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e60: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e70: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e80: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e90: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6ea0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6eb0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6ec0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6ed0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ee0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6ef0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6f00: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6f10: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6f20: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6f30: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f40: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f50: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f60: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f70: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f80: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f90: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6fa0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6fb0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6fc0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6fd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fe0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6ff0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
7000: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
7010: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
7020: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
7030: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7040: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7050: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7060: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7070: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7080: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7090: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
70a0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
70b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
70c0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
70d0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70e0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70f0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
7100: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
7110: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
7120: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
7130: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7140: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7150: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7160: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7170: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7180: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7190: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
71a0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
71b0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
71c0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
71d0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71e0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71f0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
7200: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7210: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
7220: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
7230: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7240: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7250: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7260: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7270: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7280: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7290: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
72a0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
72b0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
72c0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
72d0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
7300: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
7310: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
7320: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
7330: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7340: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7350: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7360: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7370: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7380: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7390: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
73a0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
73b0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
73c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
73d0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73e0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73f0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
7400: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
7410: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
7420: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
7430: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7440: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7450: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7460: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7470: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7480: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7490: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
74a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
74b0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
74c0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
74d0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74e0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74f0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
7500: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
7510: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
7520: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
7530: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7540: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7550: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7560: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7570: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7580: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7590: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
75a0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
75b0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
75c0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
75d0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75e0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75f0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7600: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
7610: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7620: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
7630: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7640: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7650: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7660: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7670: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7680: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7690: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
76a0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
76b0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
76c0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
76d0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76e0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76f0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
7700: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
7710: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
7720: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
7730: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7740: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7750: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7760: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7770: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7780: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7790: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
77a0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
77b0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
77c0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
77d0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77e0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
7800: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
7810: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
7820: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
7830: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7840: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7850: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7860: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7870: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7880: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7890: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
78a0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
78b0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
78c0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
78d0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78f0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
7900: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
7910: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
7920: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
7930: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7940: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7950: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7960: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7970: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7980: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7990: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
79a0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
79b0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
79c0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
79d0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79e0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79f0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
7a00: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
7a10: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
7a20: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
7a30: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a40: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a50: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a60: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a80: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a90: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7aa0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7ab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7ac0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7ad0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7ae0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7af0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7b00: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7b10: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7b20: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7b30: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b40: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b50: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b60: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b70: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b80: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b90: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7ba0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7bb0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7bc0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7bd0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7be0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bf0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7c00: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7c10: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7c20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7c30: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c40: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c50: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c60: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c70: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c80: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c90: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7ca0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7cb0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7cc0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7cd0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ce0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cf0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7d00: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7d10: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7d20: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7d30: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d40: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d50: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d60: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d70: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d80: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d90: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7da0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7db0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7dc0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7dd0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7de0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7df0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7e00: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7e10: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7e20: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7e30: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e40: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e50: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e60: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e70: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e80: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e90: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7ea0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7eb0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7ec0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7ed0: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ee0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7ef0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f00: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f20: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7f30: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f40: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f50: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f60: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f70: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f80: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f90: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7fa0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7fb0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7fc0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7fd0: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fe0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7ff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8000: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8010: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8020: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
8030: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8040: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8050: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8060: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8070: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8080: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8090: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
80a0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
80b0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
80c0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
80d0: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80e0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80f0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8100: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8110: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8120: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
8130: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8140: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8150: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8160: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8170: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81f0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8200: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8210: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8220: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8230: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8250: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8270: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8280: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8290: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
82a0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
82b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
82d0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82e0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82f0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8300: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8320: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8330: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8340: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8350: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8360: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8370: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8380: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8390: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
83a0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
83b0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
83c0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
83d0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83e0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83f0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8400: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8410: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8420: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8430: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8440: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8450: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8460: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8480: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8490: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
84a0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
84b0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
84c0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
84d0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84e0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84f0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8500: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8510: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8520: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
8530: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8540: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8550: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8560: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8570: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8580: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8590: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
85a0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
85b0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
85c0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
85d0: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85e0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85f0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8600: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8610: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8620: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
8630: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8640: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8650: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8660: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8670: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8680: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8690: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
86a0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
86b0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
86c0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
86d0: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86e0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86f0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8710: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8720: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
8730: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8740: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8750: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8760: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8770: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8780: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8790: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
87a0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
87b0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
87c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
87d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87e0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87f0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8800: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8810: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8820: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
8830: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8840: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8850: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8860: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8870: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8880: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8890: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
88a0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
88b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
88c0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
88d0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88e0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88f0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8900: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8910: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8920: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
8930: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8940: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8950: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8960: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8970: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8980: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8990: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
89a0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
89b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89c0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
89d0: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89e0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89f0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a00: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a20: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8a30: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a40: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a50: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a60: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a70: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a80: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a90: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8aa0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8ab0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8ac0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8ad0: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8ae0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8af0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b00: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b10: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b20: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8b30: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b40: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b60: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b70: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b80: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b90: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8ba0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8bb0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8bc0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8bd0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8be0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bf0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8c00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8c10: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8c20: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8c30: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c40: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c50: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c60: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c70: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c80: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c90: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8ca0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8cb0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8cc0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8cd0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ce0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cf0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8d00: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8d10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8d20: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8d30: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d40: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d50: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d60: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d70: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d80: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d90: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8da0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8db0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8dc0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8dd0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8de0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8df0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8e00: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8e10: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8e20: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8e30: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e40: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e50: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e60: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e70: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e80: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e90: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8ea0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8eb0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8ec0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8ed0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ee0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ef0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8f00: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8f10: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8f20: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8f30: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f40: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f50: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f60: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f70: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f80: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f90: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8fa0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8fb0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8fc0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8fd0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fe0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8ff0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
9000: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
9010: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
9020: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9030: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9040: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9050: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9060: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9070: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9080: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9090: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
90a0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
90b0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
90c0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
90d0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90e0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90f0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
9100: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
9110: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
9120: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
9130: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9140: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9150: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9160: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9170: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9180: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9190: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
91a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
91b0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
91c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91d0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91e0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91f0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
9200: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9210: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9220: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9230: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9240: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9250: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9260: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9270: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9280: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9290: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
92a0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
92b0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
92c0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
92d0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92e0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9300: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9310: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9320: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9330: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9340: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9350: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9360: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9370: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9380: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9390: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
93a0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
93b0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
93c0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
93d0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93e0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93f0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9400: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9410: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9420: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9430: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9440: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9450: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9460: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9470: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9480: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9490: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
94a0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
94b0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
94c0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
94d0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94e0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94f0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9500: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9510: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9520: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9530: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9540: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9550: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9560: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9570: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9580: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9590: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
95a0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
95b0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
95c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
95d0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95f0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9600: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9610: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9620: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9630: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9640: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9650: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9660: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9670: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9680: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9690: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
96a0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
96b0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
96c0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
96d0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96e0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96f0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9700: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9710: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9720: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9730: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9740: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9750: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9760: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9770: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9780: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9790: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
97a0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
97b0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
97c0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
97d0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97e0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97f0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9800: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9810: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9820: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9830: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9850: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9860: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9880: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9890: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
98a0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
98b0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
98c0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
98d0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98e0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98f0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9900: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9910: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9920: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9930: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9940: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9950: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9960: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9970: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9980: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9990: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
99a0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
99b0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
99c0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
99d0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99e0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99f0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9a00: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9a10: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9a20: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9a30: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a40: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a50: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a60: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a70: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a80: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a90: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9aa0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ab0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9ac0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9ad0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9ae0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9af0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9b00: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9b10: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9b20: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9b30: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b40: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b50: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b60: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b70: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b80: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b90: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9ba0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9bb0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9bc0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9bd0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9be0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bf0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9c00: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9c10: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9c20: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9c30: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c40: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c50: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c60: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c70: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c80: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c90: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ca0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9cb0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9cc0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9cd0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ce0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cf0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9d00: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9d10: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9d20: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9d30: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d40: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d50: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d60: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d70: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d80: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d90: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9da0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9db0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9dc0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9dd0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9de0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9df0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9e00: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9e10: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9e20: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9e30: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e40: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e50: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e60: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e70: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e80: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e90: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9ea0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9eb0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9ec0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9ed0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ee0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ef0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9f00: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9f10: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9f20: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9f30: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f40: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f50: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f60: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f70: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f80: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f90: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9fa0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9fb0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9fc0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9fd0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fe0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9ff0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a000: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a010: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a020: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a030: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a040: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a050: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a060: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a070: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a080: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a090: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a0a0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a0b0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a0c0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a0d0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0e0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0f0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a100: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a110: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a120: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a130: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a140: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a150: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a160: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a170: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a180: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a190: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a1a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a1b0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a1c0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a1d0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1e0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1f0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a200: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a210: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a220: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a230: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a240: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a250: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a260: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a270: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a280: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a290: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a2a0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a2b0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a2c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a2d0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2e0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2f0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a300: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a310: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a320: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a330: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a340: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a350: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a360: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a370: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a380: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a390: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a3a0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a3b0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a3c0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a3d0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3e0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3f0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a400: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a410: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a420: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a430: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a440: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a450: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a460: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a470: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a480: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a490: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a4a0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a4b0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a4c0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a4d0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4e0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a500: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a510: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a520: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a530: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a540: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a550: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a560: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a570: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a580: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a590: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a5a0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a5b0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a5c0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a5d0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5e0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5f0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a600: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a610: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a620: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a630: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a640: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a650: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a660: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a670: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a680: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a690: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a6a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a6b0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
a6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a6d0: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
a6e0: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
a6f0: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a700: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
a710: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
a720: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
a730: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
a740: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a750: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
a760: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
a770: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
a780: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
a790: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
a7a0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
a7b0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
a7c0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
a7d0: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
a7e0: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
a7f0: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
a800: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
a810: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
a820: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
a830: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
a840: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a850: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a860: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a870: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a880: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a890: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a8a0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a8b0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a8c0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a8d0: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a8e0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a8f0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a900: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a910: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a920: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a930: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a940: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a950: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a960: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a970: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a980: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a990: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a9a0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a9b0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a9c0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a9d0: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a9e0: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a9f0: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
aa00: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
aa10: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
aa20: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
aa30: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
aa40: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
aa50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aa60: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aa70: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
aa80: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
aa90: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
aaa0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
aab0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
aac0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
aad0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
aae0: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
aaf0: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ab00: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ab10: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ab20: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ab30: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
ab40: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
ab50: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
ab60: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
ab70: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ab80: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ab90: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aba0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
abb0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
abc0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
abd0: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
abe0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
abf0: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ac00: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ac10: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ac20: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ac30: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ac40: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ac50: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ac60: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
ac70: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
ac80: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
ac90: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
aca0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
acb0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
acc0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
acd0: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
ace0: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
acf0: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
ad00: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ad10: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ad20: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ad30: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ad40: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ad50: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ad60: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
ad70: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
ad80: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
ad90: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
ada0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
adb0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
adc0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
add0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
ade0: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
adf0: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
ae00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ae10: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ae20: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ae30: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ae40: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ae50: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ae60: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ae70: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
ae80: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
ae90: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
aea0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
aeb0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
aec0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
aed0: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
aee0: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
aef0: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
af00: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
af10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
af20: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
af30: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
af40: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
af50: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
af60: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
af70: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
af80: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
af90: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
afa0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
afb0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
afc0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
afd0: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
afe0: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
aff0: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b000: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b010: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b020: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b030: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b040: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b050: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b060: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b070: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b080: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b090: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b0a0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b0b0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b0c0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b0d0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b0e0: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b0f0: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b100: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b110: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b120: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b130: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b140: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b150: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b160: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b170: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b180: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b190: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b1a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b1b0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b1c0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b1d0: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b1e0: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b1f0: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b200: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b210: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b220: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b230: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b240: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b250: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b260: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b270: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b280: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b290: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b2a0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b2b0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b2c0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b2d0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b2e0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b2f0: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b300: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b310: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b320: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b330: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b340: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b350: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b360: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b370: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b380: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b390: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b3a0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b3b0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b3c0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b3d0: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b3e0: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b3f0: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b400: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b410: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b420: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b430: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b440: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b450: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b460: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b470: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b480: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b490: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b4a0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b4b0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b4c0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b4d0: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b4e0: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b4f0: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b500: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b510: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b520: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b530: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b540: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b550: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b560: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b570: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b580: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b590: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b5a0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b5b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b5c0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b5d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b5e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b5f0: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b600: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b610: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b620: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b630: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b640: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b650: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b660: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b670: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b680: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b690: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b6a0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b6b0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b6c0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b6d0: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b6e0: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b6f0: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b700: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b710: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b720: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b730: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b740: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b750: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b760: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b770: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b790: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b7a0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b7b0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b7c0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b7d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b7e0: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b7f0: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b800: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b810: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b820: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b830: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b840: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b850: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b860: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b870: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b880: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b890: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b8a0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b8b0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b8c0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b8d0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b8e0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b8f0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b900: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b910: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b920: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b930: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b940: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b950: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b960: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b970: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b980: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b990: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b9a0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b9b0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b9c0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b9d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b9e0: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b9f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ba00: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
ba10: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
ba20: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
ba30: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
ba40: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
ba50: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
ba60: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
ba70: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
ba80: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
ba90: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
baa0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bab0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bac0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bad0: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bae0: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
baf0: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bb00: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bb10: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bb20: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bb30: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bb40: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bb50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bb60: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
bb70: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bb80: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bb90: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bba0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bbb0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bbc0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bbd0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bbe0: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bbf0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bc00: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
bc10: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bc20: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
bc30: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bc40: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bc50: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
bc60: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bc70: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bc80: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bc90: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bca0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bcb0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bcc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bcd0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bce0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bcf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bd00: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bd10: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bd20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bd30: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bd40: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bd50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd60: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bd70: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bd80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd90: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bda0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bdb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bdc0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bdd0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bde0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bdf0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
be00: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
be10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
be20: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
be30: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
be40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
be50: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
be60: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
be70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
be80: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
be90: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
beb0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bec0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
bed0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
bee0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bef0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
bf00: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
bf10: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
bf20: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
bf30: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
bf40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
bf50: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf60: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bf70: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
bf80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf90: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bfa0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bfb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bfc0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bfd0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bfe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bff0: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c000: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c010: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c020: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c030: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c050: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c060: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c070: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c080: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c090: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c0a0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c0b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c0c0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c0d0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c0e0: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c0f0: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c100: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c110: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c120: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c130: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c140: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c150: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c170: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c180: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
c190: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
c1a0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
c1b0: 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63 61    28../* depreca
c1c0: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65  ted names */.#de
c1d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
c1e0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c1f0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c200: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c210: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c220: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c230: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c240: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
c250: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c260: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
c270: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c               SQL
c280: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
c290: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  RRNO.../*.** CAP
c2a0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
c2b0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
c2c0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
c2d0: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
c2e0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c2f0: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
c300: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
c310: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
c320: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
c330: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
c340: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
c350: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
c360: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
c370: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
c380: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
c390: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
c3a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
c3b0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
c3c0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
c3d0: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
c3e0: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
c3f0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c400: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
c410: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
c420: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c430: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c440: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c450: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c460: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c470: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c480: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c490: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c4a0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c4b0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c4c0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c4d0: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c4e0: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
c4f0: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
c500: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
c510: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
c520: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
c530: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
c540: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
c550: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
c560: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
c570: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
c580: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c590: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
c5a0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
c5b0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
c5c0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
c5d0: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
c5e0: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
c5f0: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
c600: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
c610: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
c620: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
c630: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c640: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
c650: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
c660: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
c670: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
c680: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
c690: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
c6a0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
c6b0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
c6c0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
c6d0: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
c6e0: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
c6f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
c700: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
c710: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
c720: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
c730: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
c740: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
c750: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
c760: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c770: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c780: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c790: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c7a0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c7b0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c7c0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c7d0: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
c7e0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
c7f0: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
c800: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
c810: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
c820: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
c830: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
c840: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
c850: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
c860: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
c870: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
c880: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
c890: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
c8a0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
c8b0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
c8c0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
c8d0: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
c8e0: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
c8f0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c900: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
c910: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
c920: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
c930: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
c940: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
c950: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
c960: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
c970: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
c980: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
c990: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
c9a0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
c9b0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
c9c0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
c9d0: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
c9e0: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
c9f0: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
ca00: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
ca10: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
ca20: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
ca30: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
ca40: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
ca50: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
ca60: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
ca70: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
ca80: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
ca90: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
caa0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cab0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
cac0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cad0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cae0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
caf0: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
cb00: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
cb10: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
cb20: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
cb30: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
cb40: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
cb50: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
cb60: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
cb70: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
cb80: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
cb90: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
cba0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
cbb0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
cbc0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
cbd0: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
cbe0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
cbf0: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
cc00: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
cc10: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
cc20: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
cc30: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
cc40: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
cc50: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
cc60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
cc70: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
cc80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
cc90: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
cca0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
ccb0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
ccc0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
ccd0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
cce0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
ccf0: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
cd00: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
cd10: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
cd20: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
cd30: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
cd40: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
cd50: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
cd60: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cd70: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
cd80: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
cd90: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
cda0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
cdb0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
cdc0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
cdd0: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
cde0: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
cdf0: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
ce00: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
ce10: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
ce20: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
ce30: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
ce40: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
ce50: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
ce60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
ce70: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
ce80: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
ce90: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
cea0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
ceb0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
cec0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
ced0: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
cee0: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
cef0: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
cf00: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
cf10: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
cf20: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
cf30: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
cf40: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
cf50: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
cf60: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
cf70: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
cf80: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
cf90: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
cfa0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
cfb0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
cfc0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
cfd0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
cfe0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
cff0: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d000: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d010: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d020: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d030: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d040: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d050: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d060: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d070: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d080: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d090: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d0a0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d0b0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d0c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d0d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d0e0: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d0f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d100: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d110: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d120: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d130: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d140: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d150: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d160: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d170: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d180: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d190: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d1a0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d1b0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d1c0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d1d0: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d1e0: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d1f0: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d200: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d210: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d220: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d230: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d240: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d250: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d260: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d270: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d280: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d290: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d2a0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d2b0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d2c0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d2d0: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d2e0: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d2f0: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d300: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d310: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d320: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d330: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d340: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d350: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d360: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d370: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d380: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d390: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d3a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d3b0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d3c0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d3d0: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d3e0: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d3f0: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d400: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d410: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d420: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d430: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d440: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d450: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d460: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d470: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d480: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d490: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d4a0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d4b0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d4c0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d4d0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d4e0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d4f0: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
d500: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
d510: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
d520: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
d530: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
d540: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
d550: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
d560: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d570: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
d580: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
d590: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
d5a0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
d5b0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
d5c0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
d5d0: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
d5e0: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
d5f0: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
d600: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
d610: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
d620: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
d630: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
d640: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
d650: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
d660: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
d670: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
d680: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
d690: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
d6a0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
d6b0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
d6c0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
d6d0: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
d6e0: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
d6f0: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
d700: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
d710: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
d720: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
d730: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
d740: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
d750: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
d760: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d770: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d780: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d790: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d7a0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d7b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d7c0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
d7d0: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
d7e0: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
d7f0: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
d800: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
d810: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
d820: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d830: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
d840: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
d850: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
d860: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
d870: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
d880: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
d890: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
d8a0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
d8b0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
d8c0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
d8d0: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
d8e0: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
d8f0: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
d900: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
d910: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
d920: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d930: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
d940: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
d950: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
d960: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
d970: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
d980: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
d990: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
d9a0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
d9b0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
d9c0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
d9d0: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
d9e0: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
d9f0: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
da00: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
da10: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
da20: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
da30: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
da40: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
da50: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
da60: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
da70: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
da80: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
da90: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
daa0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dab0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
dac0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
dad0: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
dae0: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
daf0: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
db00: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
db10: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
db20: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
db30: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
db40: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
db50: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
db60: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
db70: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
db80: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
db90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
dba0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
dbb0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
dbc0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
dbd0: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
dbe0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
dbf0: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
dc00: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
dc10: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
dc20: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
dc30: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
dc40: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
dc50: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
dc60: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
dc70: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
dc80: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
dc90: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
dca0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
dcb0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
dcc0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
dcd0: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
dce0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
dcf0: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
dd00: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
dd10: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
dd20: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
dd30: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
dd40: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
dd50: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
dd60: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
dd70: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
dd80: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
dd90: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
dda0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
ddb0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
ddc0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
ddd0: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
dde0: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
ddf0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
de00: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
de10: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
de20: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
de30: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
de40: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
de50: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
de60: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
de70: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
de80: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
de90: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
dea0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
deb0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
dec0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
ded0: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
dee0: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
def0: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
df00: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
df10: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
df20: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
df30: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
df40: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
df50: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
df60: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
df70: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
df80: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
df90: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
dfa0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
dfb0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
dfc0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
dfd0: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
dfe0: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
dff0: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e000: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e010: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e020: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e030: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e040: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e050: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e060: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e070: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e080: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e090: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e0a0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e0b0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e0c0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e0d0: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e0e0: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e0f0: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e100: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e110: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e120: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e130: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e140: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e150: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e160: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e170: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e180: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e190: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e1a0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e1b0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e1c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e1d0: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e1e0: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e1f0: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e200: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e210: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e220: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e230: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e240: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e250: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e260: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e270: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e280: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e290: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e2a0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e2b0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e2c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e2d0: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e2e0: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e2f0: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e300: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e310: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e320: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e330: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e340: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e350: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e360: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e370: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e380: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e390: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e3a0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e3b0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e3c0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e3d0: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e3e0: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e3f0: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e400: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e410: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e420: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e430: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e440: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e450: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e460: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e470: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e480: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e490: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e4a0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e4b0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e4c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e4d0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e4e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
e4f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
e500: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
e510: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
e520: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
e530: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e540: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
e550: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
e560: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
e570: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e580: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
e590: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
e5a0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
e5b0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
e5c0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e5d0: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e5e0: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
e5f0: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
e600: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
e610: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e620: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
e630: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
e640: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e650: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e660: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
e670: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
e680: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
e690: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
e6a0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
e6b0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
e6c0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
e6d0: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
e6e0: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
e6f0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e700: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
e710: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
e720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e730: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
e740: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
e750: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
e760: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e770: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e780: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e790: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e7a0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e7b0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e7c0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
e7d0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e7e0: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
e7f0: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
e800: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
e810: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
e820: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
e830: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
e840: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
e850: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
e860: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
e870: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
e880: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
e890: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
e8a0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
e8b0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
e8c0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
e8d0: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
e8e0: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
e8f0: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
e900: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
e910: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e920: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
e930: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
e940: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e950: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
e960: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e970: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e980: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
e990: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
e9a0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e9b0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e9c0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
e9d0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e9e0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e9f0: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ea00: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ea10: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ea20: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
ea30: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
ea40: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
ea50: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
ea60: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
ea70: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
ea80: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
ea90: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
eaa0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
eab0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
eac0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
ead0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
eae0: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
eaf0: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
eb00: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
eb10: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
eb20: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
eb30: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
eb40: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
eb50: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
eb60: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
eb70: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
eb80: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
eb90: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
eba0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ebb0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ebc0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ebd0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ebe0: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ebf0: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ec00: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ec10: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ec20: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ec30: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
ec40: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
ec50: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ec60: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
ec70: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
ec80: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
ec90: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
eca0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
ecb0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
ecc0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ecd0: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
ece0: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
ecf0: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
ed00: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
ed10: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
ed20: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
ed30: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
ed40: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
ed50: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ed60: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
ed70: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
ed80: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ed90: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
eda0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
edb0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
edc0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
edd0: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
ede0: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
edf0: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
ee00: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
ee10: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
ee20: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
ee30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
ee40: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
ee50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ee60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
ee70: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
ee80: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
ee90: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
eea0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
eeb0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
eec0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
eed0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
eee0: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
eef0: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
ef00: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
ef10: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
ef20: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
ef30: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
ef40: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
ef50: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
ef60: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
ef70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
ef80: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
ef90: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
efa0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
efb0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
efc0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
efd0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
efe0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
eff0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f000: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f010: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f020: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f030: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f040: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f050: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f060: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f070: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f080: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f090: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f0a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f0b0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f0c0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f0d0: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f0e0: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f0f0: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f100: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f110: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f120: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f130: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f140: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f150: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f160: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f170: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f180: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f190: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f1a0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f1b0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f1c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f1d0: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f1e0: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f1f0: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f200: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f210: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f220: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f230: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f240: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f250: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f260: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f270: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f280: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f290: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f2a0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f2b0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f2c0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f2d0: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f2e0: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f2f0: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f300: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f310: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f320: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f330: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f340: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f360: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f370: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f380: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f390: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f3a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f3b0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f3c0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f3d0: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f3e0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f3f0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f400: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f410: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f420: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f430: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f440: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f450: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f460: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f470: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f480: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f490: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f4a0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f4b0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f4c0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f4d0: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f4e0: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
f4f0: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
f500: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
f510: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
f520: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f530: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f540: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
f550: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f560: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
f570: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f580: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f590: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
f5a0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
f5b0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
f5c0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
f5d0: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f5e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f5f0: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
f600: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
f610: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f620: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
f630: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
f640: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
f650: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
f660: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
f670: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
f680: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
f690: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f6a0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
f6b0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
f6c0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f6d0: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
f6e0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
f6f0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f700: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
f710: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
f720: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
f730: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
f740: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
f750: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
f760: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f770: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f780: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f790: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f7a0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f7b0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f7c0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
f7d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f7e0: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
f7f0: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
f800: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
f810: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
f820: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f830: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
f840: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
f850: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
f860: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
f870: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
f880: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
f890: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
f8a0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
f8b0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
f8c0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
f8d0: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
f8e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
f8f0: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
f900: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
f910: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
f920: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
f930: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
f940: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
f950: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
f960: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
f970: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
f980: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
f990: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
f9a0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
f9b0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
f9c0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
f9d0: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
f9e0: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
f9f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fa00: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
fa10: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
fa20: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
fa30: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fa40: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fa50: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
fa60: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
fa70: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
fa80: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
fa90: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
faa0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
fab0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fac0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
fad0: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
fae0: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
faf0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fb00: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
fb10: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
fb20: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
fb30: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
fb40: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb50: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
fb60: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
fb70: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
fb80: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
fb90: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
fba0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
fbb0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
fbc0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
fbd0: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
fbe0: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
fbf0: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
fc00: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
fc10: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
fc20: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
fc30: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fc40: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
fc50: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
fc60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fc70: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
fc80: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
fc90: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fca0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
fcb0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
fcc0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
fcd0: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
fce0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
fcf0: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
fd00: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
fd10: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
fd20: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
fd30: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
fd40: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
fd50: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
fd60: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
fd70: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fd80: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
fd90: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fda0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fdb0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
fdc0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
fdd0: 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
fde0: 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
fdf0: 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
fe00: 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
fe10: 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
fe20: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fe30: 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
fe40: 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
fe50: 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
fe60: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
fe70: 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
fe80: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
fe90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fea0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
feb0: 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
fec0: 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
fed0: 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
fee0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
fef0: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
ff00: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff10: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
ff20: 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
ff30: 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
ff40: 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
ff50: 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
ff60: 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
ff70: 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
ff80: 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
ff90: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
ffa0: 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
ffb0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
ffc0: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
ffd0: 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
ffe0: 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
fff0: 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10000 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10010 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10020 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10030 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10040 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10050 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10060 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
10070 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
10080 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
10090 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
100a0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
100b0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
100c0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
100d0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
100e0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
100f0 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10100 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10110 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10120 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10130 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10140 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10150 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10160 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
10170 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
10180 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
10190 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
101a0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
101b0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
101c0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
101d0 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
101e0 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
101f0 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10200 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10210 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10220 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10230 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10240 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10250 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10260 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
10270 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
10280 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
10290 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
102a0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
102b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
102c0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
102d0 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
102e0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
102f0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10300 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10310 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10320 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10330 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10340 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10350 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10360 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
10370 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
10380 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
10390 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lure..*/.int sql
103a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
103b0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
103c0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
103d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
103e0 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e  s_init(void);.in
103f0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
10400 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
10410 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10420 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
10430 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
10440 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10450 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
10460 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
10470 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
10480 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10490 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
104a0 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
104b0 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
104c0 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
104d0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
104e0 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
104f0 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
10500 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
10510 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
10520 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
10530 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
10540 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
10550 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
10560 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
10570 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
10580 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
10590 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
105a0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
105b0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
105c0 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
105d0 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
105e0 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
105f0 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
10600 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
10610 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
10620 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
10630 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10640 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
10650 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
10660 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10670 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
10680 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
10690 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
106a0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
106b0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
106c0 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
106d0 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
106e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
106f0 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
10700 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10710 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10720 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10730 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10740 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
10750 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
10760 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
10770 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
10780 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
10790 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
107a0 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
107b0 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
107c0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
107d0 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
107e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
107f0 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10800 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10810 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10820 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10830 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10840 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
10850 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
10860 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
10870 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
10880 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
10890 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
108a0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
108b0 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
108c0 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
108d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
108e0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
108f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10900 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10910 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10920 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10930 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10940 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10950 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10960 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10970 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10980 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10990 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
109a0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
109b0 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
109c0 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  e]..*/.int sqlit
109d0 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
109e0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
109f0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10a00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10a10 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10a20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10a30 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10a40 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10a50 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10a60 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10a70 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10a80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10a90 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10aa0 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
10ab0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10ac0 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
10ad0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10ae0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10af0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10b00 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
10b10 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
10b20 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
10b30 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10b40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10b50 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
10b60 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10b70 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10b80 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10b90 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10ba0 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10bb0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10bc0 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10bd0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10be0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10bf0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10c00 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
10c10 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
10c20 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10c30 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10c40 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
10c50 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
10c60 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10c70 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10c80 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10c90 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10ca0 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10cb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10cc0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10cd0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10ce0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10cf0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10d00 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
10d10 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
10d20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
10d30 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
10d40 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
10d50 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
10d60 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10d70 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10d80 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10d90 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10da0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10db0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10dc0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10dd0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10de0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10df0 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10e00 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10e10 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
10e20 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10e30 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
10e40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10e50 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
10e60 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10e70 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10e80 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
10e90 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
10ea0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
10eb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
10ec0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
10ed0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
10ee0 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10ef0 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10f00 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
10f10 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10f20 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10f30 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
10f40 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
10f50 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
10f60 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10f70 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10f80 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
10f90 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
10fa0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
10fb0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
10fc0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
10fd0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
10fe0 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10ff0 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
11000 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11010 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
11020 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
11030 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
11040 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
11050 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
11060 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
11070 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11080 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
11090 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
110a0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
110b0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
110c0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
110d0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
110e0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
110f0 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11100 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11110 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
11120 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
11130 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
11140 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
11150 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
11160 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
11170 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11180 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
11190 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
111a0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
111b0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
111c0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
111d0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
111e0 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
111f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11200 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
11210 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
11220 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11230 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
11240 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
11250 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
11260 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
11270 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
11280 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
11290 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
112a0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
112b0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
112c0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
112d0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
112e0 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
112f0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
11300 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
11310 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
11320 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
11330 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
11340 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
11350 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
11360 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
11370 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
11380 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
11390 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
113a0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
113b0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
113c0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
113d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
113e0 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
113f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
11400 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
11410 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
11420 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
11430 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
11440 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
11450 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
11460 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
11470 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11480 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
11490 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
114a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
114b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
114c0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
114d0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
114e0 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
114f0 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
11500 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
11510 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
11520 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
11530 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
11540 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
11550 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
11560 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
11570 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
11580 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
11590 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
115a0 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
115b0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
115c0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
115d0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
115e0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
115f0 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
11600 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11610 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
11620 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
11630 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
11640 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
11650 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
11660 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
11670 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
11680 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
11690 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
116a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
116b0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
116c0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
116d0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
116e0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
116f0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
11700 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
11710 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
11720 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
11730 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
11740 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
11750 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
11760 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
11770 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
11780 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
11790 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
117a0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
117b0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
117c0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
117d0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
117e0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
117f0 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
11800 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11810 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
11820 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
11830 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
11840 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
11850 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
11860 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
11870 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11880 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11890 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
118a0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
118b0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
118c0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
118d0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
118e0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
118f0 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11900 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11910 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11920 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11930 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11940 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11950 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11960 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11970 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11980 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11990 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
119a0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
119b0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
119c0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
119d0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
119e0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
119f0 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11a00 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
11a10 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
11a20 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
11a30 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11a40 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
11a50 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
11a60 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11a70 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11a80 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11a90 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11aa0 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11ab0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11ac0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11ad0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11ae0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11af0 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11b00 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
11b10 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
11b20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11b30 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
11b40 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
11b50 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
11b60 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11b70 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11b80 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11b90 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11ba0 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11bb0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11bc0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11bd0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11be0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11bf0 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11c00 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
11c10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11c20 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
11c30 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
11c40 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
11c50 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
11c60 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11c70 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11c80 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11c90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ca0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11cb0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11cc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11cd0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11ce0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11cf0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11d00 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11d10 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
11d20 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
11d30 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
11d40 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
11d50 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11d60 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11d70 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11d80 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11d90 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11da0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11db0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11dc0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11dd0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11de0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11df0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11e00 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
11e10 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
11e20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
11e30 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
11e40 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
11e50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11e60 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11e70 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11e80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11e90 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
11ea0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
11eb0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
11ec0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
11ed0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
11ee0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11ef0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11f00 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11f10 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
11f20 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
11f30 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
11f40 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
11f50 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
11f60 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11f70 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11f80 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
11f90 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
11fa0 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
11fb0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11fc0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11fd0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11fe0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11ff0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12000 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12010 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
12020 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
12030 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
12040 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
12050 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
12060 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
12070 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
12080 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12090 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
120a0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
120b0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
120c0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
120d0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
120e0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
120f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12110 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
12120 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12130 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
12140 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
12150 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12160 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
12170 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12180 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12190 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
121a0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
121b0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
121c0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
121d0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
121e0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
121f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12200 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
12210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
12220 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
12230 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
12240 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
12250 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
12260 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
12270 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
12280 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
12290 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
122a0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
122b0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
122c0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
122d0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
122e0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
122f0 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
12300 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
12310 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
12320 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
12330 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
12340 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
12350 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12360 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
12370 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12380 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12390 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
123a0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
123b0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
123c0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
123d0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
123e0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
123f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12400 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12410 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12420 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12430 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
12440 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
12450 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
12460 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
12470 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12480 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
12490 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
124a0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
124b0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
124c0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
124d0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
124e0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
124f0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12500 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
12510 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
12520 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
12530 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
12540 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
12550 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
12560 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
12570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12580 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12590 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
125a0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
125b0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
125c0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
125d0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
125e0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
125f0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
12600 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
12610 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
12620 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
12630 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
12640 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
12650 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
12660 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
12670 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
12680 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
12690 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
126a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
126b0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
126c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
126d0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
126e0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
126f0 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
12700 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12710 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12720 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12730 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12740 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12750 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12760 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12770 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12780 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
12790 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
127a0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
127b0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
127c0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
127d0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
127e0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
127f0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12800 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
12810 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
12820 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12830 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
12840 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12850 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
12860 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
12870 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12880 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12890 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
128a0 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
128b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
128c0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
128d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
128e0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
128f0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12900 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
12910 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
12920 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12930 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
12940 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
12950 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
12960 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12970 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12980 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12990 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
129a0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
129b0 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
129c0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
129d0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
129e0 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
129f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12a00 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
12a10 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
12a20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a30 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
12a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12a50 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
12a60 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12a70 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12a80 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12a90 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12aa0 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12ab0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12ac0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12ad0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ae0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12af0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12b00 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
12b10 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12b20 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12b30 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
12b40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12b50 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12b60 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12b70 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12b80 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12ba0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12bb0 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12bc0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12bd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12be0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12bf0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12c00 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
12c10 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12c20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12c30 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
12c40 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12c50 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
12c60 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12c70 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12c80 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12c90 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12ca0 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12cb0 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12cc0 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12cd0 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12ce0 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12cf0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12d00 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
12d10 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12d20 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12d30 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
12d40 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
12d50 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
12d60 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12d70 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12d80 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12d90 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12da0 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12db0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12dc0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12dd0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12de0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12df0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12e00 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
12e10 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
12e20 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
12e30 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12e40 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
12e50 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
12e60 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
12e70 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
12e80 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
12e90 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
12ea0 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
12eb0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
12ec0 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
12ed0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
12ee0 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
12ef0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12f00 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
12f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
12f20 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
12f30 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
12f40 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
12f50 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12f60 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12f70 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
12f80 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
12f90 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12fa0 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
12fb0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
12fc0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
12fd0 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
12fe0 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
12ff0 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
13000 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
13010 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
13020 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
13030 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
13040 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
13050 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
13060 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
13070 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
13080 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
13090 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
130a0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
130b0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
130c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
130d0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
130e0 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
130f0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13100 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
13110 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
13120 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
13130 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
13140 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
13150 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
13160 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
13170 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
13180 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
13190 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
131a0 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
131b0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
131c0 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
131d0 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
131e0 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
131f0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13200 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
13210 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
13220 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
13230 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
13240 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
13250 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
13260 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
13270 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
13280 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
13290 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
132a0 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
132b0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
132c0 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
132d0 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
132e0 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
132f0 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
13300 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
13310 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
13320 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
13330 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13340 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
13350 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
13360 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
13370 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
13380 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
13390 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
133a0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
133b0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
133c0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
133d0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
133e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
133f0 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
13400 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
13410 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
13420 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
13430 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
13440 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
13450 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
13460 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
13470 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
13480 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
13490 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
134a0 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
134b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
134c0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
134d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
134e0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
134f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13500 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
13510 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
13520 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
13530 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13540 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
13550 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
13560 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
13570 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
13580 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
13590 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
135a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
135b0 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
135c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
135d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
135e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
135f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
13600 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
13610 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
13620 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
13630 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
13640 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
13650 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
13660 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
13670 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13680 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13690 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
136a0 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
136b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
136c0 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
136d0 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
136e0 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
136f0 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
13700 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
13710 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
13720 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
13730 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
13740 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
13750 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
13760 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
13770 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13780 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
13790 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
137a0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
137b0 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
137c0 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
137d0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
137e0 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
137f0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
13800 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
13810 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
13820 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
13830 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
13840 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
13850 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
13860 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
13870 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
13880 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
13890 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
138a0 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
138b0 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
138c0 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
138d0 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
138e0 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
138f0 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
13900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
13910 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
13920 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
13930 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
13940 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
13950 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13960 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
13970 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
13980 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
13990 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
139a0 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
139b0 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
139c0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
139d0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
139e0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
139f0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13a00 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
13a10 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
13a20 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
13a30 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13a40 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
13a50 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
13a60 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
13a70 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
13a80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13a90 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
13aa0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
13ab0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13ac0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13ad0 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13ae0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13af0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13b00 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13b10 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13b20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
13b30 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13b40 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
13b50 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
13b60 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
13b70 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
13b80 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
13b90 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
13ba0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13bb0 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
13bc0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13bd0 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13be0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13bf0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13c00 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13c10 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13c20 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
13c30 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
13c40 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
13c50 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
13c60 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
13c70 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
13c80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13c90 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
13ca0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
13cb0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13cc0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13cd0 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13ce0 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13cf0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13d00 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13d10 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13d20 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13d30 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13d40 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13d50 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
13d60 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
13d70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13d80 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
13d90 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
13da0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
13db0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13dc0 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13dd0 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13de0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13df0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13e00 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13e10 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13e20 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13e30 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13e40 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13e50 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13e60 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
13e70 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
13e80 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13e90 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
13ea0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13eb0 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
13ec0 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
13ed0 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
13ee0 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
13ef0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
13f00 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13f10 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
13f20 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13f30 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13f40 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13f50 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
13f60 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
13f70 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
13f80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13f90 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13fa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
13fb0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13fc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13fd0 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
13fe0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13ff0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
14000 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
14010 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14020 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14030 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14040 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
14050 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
14060 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
14070 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
14080 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
14090 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
140a0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
140b0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
140c0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
140d0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
140e0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
140f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14100 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14110 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
14120 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
14130 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
14140 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
14150 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14160 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14170 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14180 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14190 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
141a0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
141b0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
141c0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
141d0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
141e0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
141f0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
14200 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14210 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
14220 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
14230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14240 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14250 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14260 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
14270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14280 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
142a0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
142b0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
142c0 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
142d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
142e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
142f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14300 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14310 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14320 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
14330 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
14340 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
14350 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
14360 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
14370 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14380 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
14390 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
143a0 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
143b0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
143c0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
143d0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
143e0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
143f0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
14400 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14410 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
14420 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
14430 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
14440 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
14450 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14460 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14470 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14480 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14490 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
144a0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
144b0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
144c0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
144d0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
144e0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
144f0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14500 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14510 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14520 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14530 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
14540 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
14550 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
14560 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
14570 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14580 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14590 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
145a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
145b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
145c0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
145d0 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
145e0 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
145f0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14600 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14610 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
14620 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
14630 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
14640 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
14650 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14660 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
14670 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
14680 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
14690 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
146a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
146b0 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
146c0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
146d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
146e0 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
146f0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14700 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14710 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
14720 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
14730 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
14740 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
14750 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
14760 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
14770 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
14780 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14790 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
147a0 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
147b0 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
147c0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
147d0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
147e0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
147f0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14800 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14810 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14820 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
14830 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14840 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
14850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14860 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14870 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14880 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
14890 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
148a0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
148b0 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
148c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
148d0 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
148e0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
148f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14900 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14910 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14920 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14930 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14940 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14950 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14960 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14970 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14980 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14990 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
149a0 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
149b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
149c0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
149d0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
149e0 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
149f0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14a00 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14a10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14a20 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14a30 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14a50 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
14a60 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
14a70 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
14a80 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14a90 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
14aa0 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
14ab0 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
14ac0 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14ad0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14ae0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14af0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14b00 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14b10 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14b20 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
14b30 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
14b40 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14b50 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
14b60 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
14b70 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
14b80 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
14b90 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
14ba0 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
14bb0 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
14bc0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14bd0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14be0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14bf0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14c10 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14c20 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
14c30 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
14c40 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
14c50 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14c60 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14c70 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
14c80 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
14c90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14ca0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
14cb0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14cc0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14cd0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14ce0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14cf0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14d00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14d10 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14d20 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
14d30 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14d40 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
14d50 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
14d60 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
14d70 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
14d80 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
14d90 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
14da0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
14db0 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
14dc0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14dd0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14de0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14df0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14e00 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14e10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14e20 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14e30 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14e40 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14e50 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
14e60 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
14e70 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
14e80 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
14e90 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
14ea0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
14eb0 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14ec0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
14ed0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14ee0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14ef0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
14f00 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
14f10 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14f20 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
14f30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14f40 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f60 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
14f70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14f80 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
14f90 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
14fa0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14fb0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
14fc0 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14fd0 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14fe0 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
14ff0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15000 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
15010 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
15020 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
15030 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
15040 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
15050 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
15060 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
15070 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15080 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
15090 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
150a0 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
150b0 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
150c0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
150d0 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
150e0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
150f0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
15100 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
15110 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
15120 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
15130 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
15140 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
15150 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
15160 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
15170 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
15180 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
15190 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
151a0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
151b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
151c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
151d0 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
151e0 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
151f0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
15200 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
15210 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
15220 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
15230 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
15240 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
15250 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
15260 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
15270 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15280 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
15290 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
152a0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
152b0 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
152c0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
152d0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
152e0 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
152f0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
15300 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
15310 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
15320 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
15330 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
15340 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
15350 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
15360 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15370 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15380 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
15390 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
153a0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
153b0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
153c0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
153d0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
153e0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
153f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15400 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15410 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
15420 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
15430 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
15440 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
15450 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
15460 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
15470 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15480 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
15490 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
154a0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
154b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
154c0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
154d0 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
154e0 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
154f0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15500 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15510 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
15520 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
15530 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
15540 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
15550 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
15560 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
15570 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
15580 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
15590 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
155a0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
155b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
155c0 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
155d0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
155e0 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
155f0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15600 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15610 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
15620 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
15630 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
15640 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
15650 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
15660 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
15670 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
15680 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
15690 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
156a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
156b0 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
156c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
156d0 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
156e0 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
156f0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15700 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15710 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15720 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
15730 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
15740 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
15750 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
15760 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
15770 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
15780 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
15790 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
157a0 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
157b0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
157c0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
157d0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
157e0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
157f0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15800 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15810 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15820 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
15830 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
15840 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
15850 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
15860 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
15870 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15880 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
15890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
158a0 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
158b0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
158c0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
158d0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
158e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
158f0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15900 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15910 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15920 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15930 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15940 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15950 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15960 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
15970 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15980 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
15990 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
159a0 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
159b0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
159c0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
159d0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
159e0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
159f0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15a00 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15a10 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15a20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15a30 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15a40 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15a50 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
15a60 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
15a70 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
15a80 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
15a90 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
15aa0 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
15ab0 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15ac0 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15ad0 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15ae0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15af0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15b00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15b10 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15b20 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15b30 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15b40 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
15b50 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
15b60 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
15b70 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
15b80 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
15b90 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
15ba0 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
15bb0 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15bc0 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15bd0 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15be0 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15bf0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15c00 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15c10 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15c30 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15c40 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
15c50 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
15c60 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
15c70 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
15c80 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
15c90 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
15ca0 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15cb0 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15cc0 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15cd0 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15ce0 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15cf0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15d00 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15d10 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15d20 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15d30 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15d40 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15d50 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15d60 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
15d70 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
15d80 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
15d90 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
15da0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
15db0 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15dc0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15dd0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15df0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15e00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15e10 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15e20 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15e30 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15e40 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15e50 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15e60 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
15e70 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
15e80 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
15e90 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
15ea0 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
15eb0 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
15ec0 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
15ed0 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15ee0 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15ef0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15f00 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15f10 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15f20 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
15f30 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
15f40 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
15f50 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15f60 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
15f70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15f80 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
15f90 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15fa0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15fb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15fc0 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
15fd0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15fe0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
15ff0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
16000 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
16010 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
16020 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
16030 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
16040 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
16050 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
16060 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
16070 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
16080 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
16090 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
160a0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
160b0 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
160c0 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
160d0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
160e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
160f0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
16100 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16110 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
16120 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16130 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
16140 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16150 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
16160 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
16170 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
16180 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
16190 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
161a0 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
161b0 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
161c0 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
161d0 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
161e0 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
161f0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16200 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
16210 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16220 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
16230 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
16240 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
16250 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
16260 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
16270 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
16280 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
16290 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
162a0 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
162b0 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
162c0 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
162d0 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
162e0 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
162f0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
16300 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
16310 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
16320 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
16330 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  lue..** </dl>.*/
16340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16350 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
16360 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
16370 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16380 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16390 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
163a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
163b0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
163c0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
163d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
163e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
163f0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16400 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16410 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16420 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16430 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
16440 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
16450 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
16470 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
16480 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16490 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
164a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
164b0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
164c0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
164d0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
164e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
164f0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16500 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16510 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
16520 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16530 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
16540 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
16550 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
16560 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
16570 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
16580 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16590 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
165a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
165b0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
165c0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
165d0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
165e0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
165f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16600 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16610 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
16620 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
16640 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
16650 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16660 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16670 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
16680 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
16690 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
166a0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
166b0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
166c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
166d0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
166e0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
166f0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16710 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
16720 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
16730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16740 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
16750 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
16760 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
16770 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16780 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
16790 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
167a0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
167b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
167c0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
167d0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
167e0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
167f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16800 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
16810 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
16820 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
16830 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
16840 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
16850 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
16860 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
16870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16880 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16890 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
168a0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
168b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
168c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
168d0 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
168e0 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
168f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16900 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
16910 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
16920 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
16930 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a */../*.** CAPI
16940 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
16950 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
16960 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
16970 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
16980 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
16990 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
169a0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
169b0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
169c0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
169d0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
169e0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
169f0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16a00 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16a10 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
16a20 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
16a30 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
16a40 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
16a50 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
16a60 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
16a70 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
16a80 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
16a90 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
16aa0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
16ab0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
16ac0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16ad0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16ae0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
16af0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
16b00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
16b10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16b20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
16b30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
16b40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
16b50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
16b60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
16b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16b80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
16b90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16ba0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16bb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16bc0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16bd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16be0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
16bf0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
16c00 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
16c10 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16c20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
16c30 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
16c40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16c50 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
16c70 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16c80 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16c90 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16ca0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16cb0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16cc0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16cd0 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16ce0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16cf0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16d00 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16d10 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16d20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
16d30 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
16d40 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
16d50 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
16d60 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
16d70 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
16d80 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
16d90 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
16da0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
16db0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
16dc0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16dd0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16de0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16df0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
16e00 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
16e10 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16e20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16e30 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
16e40 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16e50 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16e60 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16e70 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
16e80 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
16e90 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16ea0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
16eb0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
16ec0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
16ed0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16ee0 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
16ef0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
16f00 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
16f10 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
16f20 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
16f30 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
16f40 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
16f50 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
16f60 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
16f70 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
16f80 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
16f90 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
16fa0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
16fb0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
16fc0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
16fd0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
16fe0 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
16ff0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
17000 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
17010 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
17020 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
17030 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
17040 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
17050 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
17060 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
17070 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17080 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17090 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
170a0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
170b0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
170c0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
170d0 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
170e0 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
170f0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
17100 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17110 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17120 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
17130 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
17140 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
17150 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
17160 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
17170 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17180 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17190 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
171a0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
171b0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
171c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
171d0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
171e0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
171f0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17200 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
17210 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
17220 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
17230 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
17240 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
17250 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
17260 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
17270 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17280 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17290 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
172a0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
172b0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
172c0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
172d0 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
172e0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
172f0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17300 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17310 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
17320 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
17330 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
17340 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
17350 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
17360 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
17370 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17380 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17390 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
173a0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
173b0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
173c0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
173d0 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
173e0 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
173f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17400 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17410 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17420 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
17430 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
17440 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
17450 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
17460 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
17470 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17480 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17490 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
174a0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
174b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
174c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
174d0 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
174e0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
174f0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17500 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17510 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17520 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
17530 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
17540 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
17550 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
17560 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
17570 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17580 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17590 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
175a0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
175b0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
175c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
175d0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
175e0 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
175f0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
17600 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17610 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17620 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
17630 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
17640 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
17650 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
17660 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
17670 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
17680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
17690 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
176a0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
176b0 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
176c0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
176d0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
176e0 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
176f0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
17700 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
17710 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
17720 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
17730 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
17740 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
17750 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
17760 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
17770 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
17780 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
17790 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
177a0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
177b0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
177c0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
177d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
177e0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
177f0 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
17800 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
17810 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17820 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
17830 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
17840 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
17850 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
17860 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
17870 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
17880 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
17890 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
178a0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
178b0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
178c0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
178d0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
178e0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
178f0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17900 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17910 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17920 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
17930 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
17940 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
17950 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
17960 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
17970 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
17980 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17990 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
179a0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
179b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
179c0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
179d0 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
179e0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
179f0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17a00 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17a10 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17a20 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
17a30 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
17a40 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
17a50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17a60 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
17a70 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
17a80 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
17a90 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
17aa0 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
17ab0 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17ac0 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17ad0 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17ae0 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17af0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17b00 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17b10 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17b20 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
17b30 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
17b40 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
17b50 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
17b60 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
17b70 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
17b80 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
17b90 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17ba0 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17bb0 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17bc0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17bd0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17be0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17bf0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17c00 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17c10 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17c20 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
17c30 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
17c40 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17c50 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
17c60 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
17c70 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
17c80 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
17c90 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
17ca0 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17cb0 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17cc0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17cd0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17ce0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17cf0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17d00 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17d10 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17d20 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
17d30 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
17d40 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
17d50 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
17d60 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
17d70 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
17d80 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17d90 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
17da0 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17db0 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17dc0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17dd0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17de0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17df0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17e00 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17e10 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17e20 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17e30 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17e40 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17e50 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17e60 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17e70 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17e80 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17e90 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17ea0 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17eb0 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17ec0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17ed0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17ee0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17ef0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17f00 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17f10 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17f20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17f30 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17f40 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17f50 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17f60 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17f70 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17f80 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17f90 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17fa0 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17fb0 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17fc0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17fd0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17fe0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17ff0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
18000 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
18010 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
18020 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
18030 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
18040 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
18050 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
18060 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
18070 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
18080 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
18090 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
180a0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
180b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
180c0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
180d0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
180e0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
180f0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
18100 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
18110 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
18120 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
18130 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
18140 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
18150 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
18160 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18170 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
18180 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
18190 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
181a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
181b0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
181c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
181d0 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
181e0 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
181f0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
18200 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
18210 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
18220 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18230 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
18240 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
18250 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
18260 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
18270 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
18280 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
18290 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
182a0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
182b0 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
182c0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
182d0 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
182e0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
182f0 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
18300 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
18310 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
18320 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
18330 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
18340 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
18350 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
18360 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
18370 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
18380 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
18390 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
183a0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
183b0 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
183c0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
183d0 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
183e0 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
183f0 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
18400 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
18410 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
18420 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
18430 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
18440 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
18450 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
18460 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
18470 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
18480 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
18490 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
184a0 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
184b0 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
184c0 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
184d0 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
184e0 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
184f0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
18500 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
18510 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
18520 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
18530 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
18540 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
18550 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
18560 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
18570 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
18580 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
18590 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
185a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
185b0 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
185c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
185d0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
185e0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
185f0 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
18600 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
18610 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
18620 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
18630 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
18640 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18650 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
18660 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18670 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
18680 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
18690 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
186a0 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
186b0 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
186c0 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
186d0 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
186e0 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
186f0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18700 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
18710 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
18720 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
18730 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
18740 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18750 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
18760 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
18770 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
18780 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
18790 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
187a0 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
187b0 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
187c0 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
187d0 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
187e0 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
187f0 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
18800 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
18810 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
18820 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
18830 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
18840 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
18850 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
18860 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
18870 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
18880 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
18890 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
188a0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
188b0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
188c0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
188d0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
188e0 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
188f0 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
18900 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
18910 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
18920 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
18930 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
18940 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
18950 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
18960 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
18970 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
18980 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
18990 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
189a0 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
189b0 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
189c0 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
189d0 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
189e0 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
189f0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18a00 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
18a10 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18a20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
18a30 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
18a40 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
18a50 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
18a60 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
18a70 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
18a80 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18a90 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18aa0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18ab0 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18ac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18ad0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18ae0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
18af0 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18b00 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18b10 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
18b20 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
18b30 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
18b40 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
18b50 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18b60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
18b70 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
18b80 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
18b90 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
18ba0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
18bb0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
18bc0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
18bd0 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
18be0 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
18bf0 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
18c00 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
18c10 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18c20 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
18c30 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
18c40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18c50 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
18c60 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
18c70 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
18c80 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
18c90 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
18ca0 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
18cb0 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
18cc0 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
18cd0 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
18ce0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18cf0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18d00 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
18d10 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
18d20 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
18d30 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
18d40 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
18d50 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
18d60 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
18d70 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
18d80 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
18d90 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
18da0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
18db0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
18dc0 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
18dd0 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
18de0 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
18df0 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
18e00 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18e10 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18e20 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18e30 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18e40 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18e50 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
18e60 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18e70 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18e80 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18e90 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18ea0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18eb0 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18ec0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18ed0 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18ee0 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18ef0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18f00 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18f10 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18f20 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18f30 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18f40 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18f50 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18f60 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18f70 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
18f80 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18f90 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18fa0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18fb0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18fc0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18fd0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18fe0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18ff0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
19000 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
19010 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
19020 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
19030 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
19040 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
19050 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
19060 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
19070 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
19080 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
19090 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
190a0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
190b0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
190c0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
190d0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
190e0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
190f0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
19100 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
19110 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
19120 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
19130 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
19140 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
19150 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
19160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19170 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
19180 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
19190 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
191a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
191b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
191c0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
191d0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
191e0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
191f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
19200 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19210 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
19220 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
19230 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
19240 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
19250 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
19260 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
19270 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
19280 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
19290 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
192a0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
192b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
192c0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
192d0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
192e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
192f0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19300 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
19310 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
19320 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
19330 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
19340 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
19350 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
19360 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
19370 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
19380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
19390 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
193a0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
193b0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
193c0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
193d0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
193e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
193f0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
19400 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
19410 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19420 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19430 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19440 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
19450 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
19460 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
19470 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
19480 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
19490 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
194a0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
194b0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
194c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
194d0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
194e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
194f0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19500 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
19510 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
19520 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
19530 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
19540 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
19550 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
19560 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
19570 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19580 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
19590 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
195a0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
195b0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
195c0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
195d0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
195e0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
195f0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19600 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19610 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
19620 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
19630 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
19640 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
19650 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
19660 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
19670 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
19680 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
19690 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
196a0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
196b0 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
196c0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
196d0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
196e0 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
196f0 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
19700 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19710 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
19720 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
19730 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
19740 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
19750 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
19760 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
19770 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
19780 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
19790 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
197a0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
197b0 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
197c0 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
197d0 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
197e0 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
197f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19800 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
19810 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
19820 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
19830 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
19840 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
19850 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
19860 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
19870 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
19880 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
19890 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
198a0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
198b0 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
198c0 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
198d0 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
198e0 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
198f0 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
19900 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
19910 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
19920 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
19930 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
19940 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
19950 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
19960 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
19970 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
19980 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
19990 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
199a0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
199b0 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
199c0 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
199d0 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
199e0 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
199f0 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
19a00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
19a10 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19a20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
19a30 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
19a40 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
19a50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
19a60 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
19a70 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
19a80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19a90 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
19aa0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
19ab0 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
19ac0 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
19ad0 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
19ae0 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
19af0 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
19b00 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
19b10 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
19b20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
19b30 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
19b40 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
19b50 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19b60 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
19b70 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
19b80 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
19b90 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
19ba0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
19bb0 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
19bc0 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
19bd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
19be0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
19bf0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19c00 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
19c10 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
19c20 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
19c30 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
19c40 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
19c50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
19c60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
19c70 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
19c80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
19c90 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
19ca0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
19cb0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
19cc0 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
19cd0 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
19ce0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
19cf0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
19d00 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
19d10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
19d20 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
19d30 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
19d40 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19d50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
19d60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19d70 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
19d80 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
19d90 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
19da0 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
19db0 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
19dc0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
19dd0 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
19de0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19df0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
19e00 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
19e10 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
19e20 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19e30 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
19e40 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19e50 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
19e60 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19e70 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19e80 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
19e90 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
19ea0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
19eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19ec0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
19ed0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19ee0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
19ef0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
19f00 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19f10 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
19f20 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
19f30 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
19f40 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19f50 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19f60 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19f70 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19f80 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19f90 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19fa0 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19fb0 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19fc0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
19fd0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
19fe0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19ff0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1a000 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1a010 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1a020 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1a030 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1a040 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1a050 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1a060 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1a070 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1a080 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1a090 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1a0a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1a0b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a0c0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1a0d0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1a0e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a0f0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1a100 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1a110 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1a120 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1a130 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1a140 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1a150 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1a160 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1a170 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1a180 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1a190 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1a1a0 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1a1b0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1a1c0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1a1d0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1a1e0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1a1f0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1a200 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1a210 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1a220 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1a230 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1a240 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1a250 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1a260 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1a270 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1a280 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1a290 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1a2a0 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1a2b0 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1a2c0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1a2d0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1a2e0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1a2f0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1a300 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1a310 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1a320 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1a330 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1a340 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1a350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1a360 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1a370 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1a380 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1a390 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a3a0 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1a3b0 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1a3c0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a3d0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1a3e0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1a3f0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1a400 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1a410 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1a420 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a430 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1a440 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1a450 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1a460 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1a470 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1a480 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1a490 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1a4a0 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a4b0 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1a4c0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1a4d0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1a4e0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1a4f0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1a500 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1a510 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1a520 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1a530 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1a540 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1a550 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1a560 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1a570 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1a580 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1a590 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1a5a0 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1a5b0 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1a5c0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1a5d0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1a5e0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1a5f0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1a600 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1a610 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1a620 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1a630 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1a640 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1a650 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a660 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a670 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1a680 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1a690 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1a6a0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1a6b0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1a6c0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1a6d0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1a6e0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1a6f0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1a700 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1a710 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1a720 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1a730 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1a740 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1a750 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1a760 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1a770 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1a780 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1a790 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a7a0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1a7b0 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1a7c0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1a7d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a7e0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a7f0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a800 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1a810 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1a820 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1a830 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1a840 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1a850 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1a860 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1a870 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1a880 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1a890 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1a8a0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1a8b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a8c0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1a8d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a8e0 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1a8f0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a900 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1a910 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1a920 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a930 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1a940 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1a950 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a960 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1a970 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1a980 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1a990 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1a9a0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1a9b0 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1a9c0 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1a9d0 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1a9e0 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1a9f0 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1aa00 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1aa10 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1aa20 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1aa30 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1aa40 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1aa50 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1aa60 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1aa70 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1aa80 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1aa90 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1aaa0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1aab0 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1aac0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1aad0 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1aae0 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1aaf0 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1ab00 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1ab10 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1ab20 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1ab30 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1ab40 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ab50 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1ab60 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1ab70 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1ab80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ab90 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1aba0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1abb0 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1abc0 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1abd0 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1abe0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1abf0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1ac00 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1ac10 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1ac20 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1ac30 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1ac40 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1ac50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1ac60 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1ac70 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1ac80 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1ac90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1aca0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1acb0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1acc0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1acd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1ace0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1acf0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1ad00 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1ad10 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1ad20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1ad30 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1ad40 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1ad50 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1ad60 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1ad70 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1ad80 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1ad90 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1ada0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1adb0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1adc0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1add0 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1ade0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1adf0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1ae00 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1ae10 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1ae20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1ae30 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1ae40 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1ae50 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1ae60 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1ae70 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ae80 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ae90 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1aea0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1aeb0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1aec0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1aed0 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1aee0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1aef0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1af00 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1af10 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1af20 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1af30 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1af40 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1af50 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1af60 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1af70 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1af80 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1af90 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1afa0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1afb0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1afc0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1afd0 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1afe0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1aff0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1b000 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1b010 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1b020 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1b030 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1b040 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1b050 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1b060 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1b070 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1b080 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1b090 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1b0a0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1b0b0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1b0c0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1b0d0 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1b0e0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1b0f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1b100 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1b110 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1b120 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1b130 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1b140 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1b150 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1b160 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1b170 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1b180 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1b190 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1b1a0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1b1b0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1b1c0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1b1d0 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1b1e0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1b1f0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b200 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1b210 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1b220 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1b230 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1b240 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1b250 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1b260 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1b270 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1b280 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1b290 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1b2a0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1b2b0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1b2c0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1b2d0 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1b2e0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1b2f0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1b300 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1b310 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1b320 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1b330 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1b340 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1b350 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1b360 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1b370 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b380 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b390 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1b3a0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1b3b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b3c0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1b3d0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b3e0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1b3f0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b400 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1b410 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1b420 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1b430 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1b440 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1b450 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1b460 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b470 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1b480 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b490 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1b4a0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b4b0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1b4c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1b4d0 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1b4e0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1b4f0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1b500 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1b510 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1b520 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1b530 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1b540 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1b550 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1b560 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1b570 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1b580 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1b590 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1b5a0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1b5b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1b5c0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1b5d0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1b5e0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b5f0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1b600 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1b610 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1b620 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1b630 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1b640 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1b650 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1b660 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1b670 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1b680 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b690 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1b6a0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1b6b0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1b6c0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1b6d0 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1b6e0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1b6f0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1b700 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1b710 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b720 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1b730 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b740 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1b750 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1b760 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b770 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1b780 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1b790 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1b7a0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1b7b0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1b7c0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b7d0 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1b7e0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1b7f0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1b800 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1b810 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1b820 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1b830 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1b840 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1b850 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1b860 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1b870 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1b880 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1b890 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1b8a0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1b8b0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1b8c0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1b8d0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1b8e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1b8f0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1b900 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1b910 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1b920 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1b930 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1b940 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1b950 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1b960 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1b970 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1b980 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1b990 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1b9a0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1b9b0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1b9c0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1b9d0 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1b9e0 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b9f0 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1ba00 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1ba10 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1ba20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1ba30 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1ba40 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1ba50 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1ba60 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1ba70 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1ba80 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1ba90 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1baa0 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1bab0 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1bac0 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1bad0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1bae0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1baf0 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1bb00 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1bb10 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1bb20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1bb30 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1bb40 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1bb50 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1bb60 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1bb70 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1bb80 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1bb90 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1bba0 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1bbb0 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1bbc0 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1bbd0 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1bbe0 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1bbf0 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1bc00 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1bc10 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1bc20 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1bc30 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1bc40 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1bc50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1bc60 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1bc70 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1bc80 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1bc90 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1bca0 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1bcb0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1bcc0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1bcd0 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1bce0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1bcf0 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1bd00 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1bd10 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1bd20 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1bd30 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1bd40 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1bd50 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1bd60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1bd70 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1bd80 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1bd90 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1bda0 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1bdb0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1bdc0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1bdd0 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1bde0 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1bdf0 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1be00 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1be10 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1be20 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1be30 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1be40 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1be50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1be60 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1be70 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1be80 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1be90 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1bea0 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1beb0 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1bec0 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1bed0 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1bee0 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1bef0 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1bf00 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1bf10 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1bf20 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1bf30 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1bf40 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1bf50 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1bf60 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1bf70 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bf80 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1bf90 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1bfa0 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1bfb0 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1bfc0 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1bfd0 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1bfe0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1bff0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1c000 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1c010 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1c020 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1c030 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1c040 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1c050 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1c060 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c070 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1c080 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1c090 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1c0a0 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1c0b0 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1c0c0 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1c0d0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1c0e0 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1c0f0 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1c100 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1c110 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1c120 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1c130 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1c140 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1c150 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1c160 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1c170 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1c180 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1c190 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1c1a0 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1c1b0 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1c1c0 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1c1d0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1c1e0 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1c1f0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1c200 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1c210 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1c220 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1c230 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1c240 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1c250 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1c260 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1c270 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1c280 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1c290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1c2a0 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1c2b0 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1c2c0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1c2d0 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1c2e0 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1c2f0 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1c300 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1c310 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1c320 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1c330 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1c340 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1c350 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1c360 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1c370 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1c380 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1c390 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1c3a0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1c3b0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1c3c0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1c3d0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1c3e0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1c3f0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1c400 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1c410 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1c420 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1c430 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1c440 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1c450 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1c460 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1c470 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1c480 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1c490 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1c4a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c4b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c4c0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1c4d0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c4e0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1c4f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c500 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1c510 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1c520 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1c530 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c540 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c550 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c560 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c570 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c580 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1c590 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c5a0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c5b0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c5c0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c5d0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c5e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c5f0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1c600 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1c610 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1c620 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1c630 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1c640 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1c650 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1c660 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c670 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c680 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1c690 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1c6a0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1c6b0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1c6c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c6d0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1c6e0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1c6f0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1c700 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1c710 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1c720 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1c730 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c740 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1c750 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c760 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1c770 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1c780 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c790 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1c7a0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1c7b0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1c7c0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1c7d0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1c7e0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1c7f0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1c800 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1c810 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1c820 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1c830 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1c840 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c850 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1c860 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1c870 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1c880 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1c890 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1c8a0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1c8b0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c8c0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1c8d0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1c8e0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1c8f0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1c900 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1c910 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1c920 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1c930 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1c940 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1c950 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c960 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c970 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c980 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c990 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1c9a0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c9b0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c9c0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c9d0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c9e0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c9f0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1ca00 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1ca10 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1ca20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1ca30 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1ca40 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1ca50 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1ca60 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1ca70 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1ca80 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1ca90 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1caa0 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1cab0 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1cac0 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1cad0 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1cae0 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1caf0 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1cb00 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1cb10 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1cb20 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1cb30 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1cb40 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1cb50 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1cb60 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1cb70 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1cb80 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1cb90 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1cba0 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1cbb0 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1cbc0 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1cbd0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1cbe0 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1cbf0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1cc00 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1cc10 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1cc20 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1cc30 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1cc40 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1cc50 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1cc60 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1cc70 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1cc80 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1cc90 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1cca0 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1ccb0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1ccc0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1ccd0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1cce0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1ccf0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1cd00 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1cd10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1cd20 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1cd30 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1cd40 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1cd50 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1cd60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cd70 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1cd80 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1cd90 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1cda0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1cdb0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1cdc0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1cdd0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1cde0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1cdf0 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1ce00 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1ce10 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1ce20 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1ce30 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1ce40 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1ce50 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1ce60 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1ce70 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1ce80 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1ce90 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1cea0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1ceb0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1cec0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1ced0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1cee0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1cef0 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1cf00 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1cf10 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1cf20 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1cf30 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1cf40 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1cf50 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1cf60 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1cf70 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1cf80 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1cf90 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1cfa0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cfb0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1cfc0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1cfd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1cfe0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1cff0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1d000 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1d010 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1d020 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1d030 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d040 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1d050 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1d060 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1d070 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1d080 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1d090 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1d0a0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1d0b0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1d0c0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1d0d0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1d0e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1d0f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d100 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1d110 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1d120 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1d130 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1d140 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1d150 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1d160 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1d170 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1d180 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1d190 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1d1a0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1d1b0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1d1c0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1d1d0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1d1e0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1d1f0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1d200 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1d210 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1d220 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1d230 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1d240 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1d250 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1d260 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1d270 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1d280 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1d290 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1d2a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1d2b0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1d2c0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1d2d0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1d2e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1d2f0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1d300 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1d310 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1d320 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1d330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1d340 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1d350 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1d360 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1d370 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1d380 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1d390 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1d3a0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1d3b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d3c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d3d0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1d3e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1d3f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1d400 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1d410 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1d420 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1d430 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1d440 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d450 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1d460 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1d470 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1d480 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1d490 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1d4a0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1d4b0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1d4c0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1d4d0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d4e0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1d4f0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1d500 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1d510 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1d520 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1d530 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1d540 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1d550 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1d560 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1d570 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1d580 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1d590 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1d5a0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1d5b0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1d5c0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1d5d0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1d5e0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1d5f0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1d600 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1d610 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1d620 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1d630 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1d640 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1d650 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1d660 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1d670 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1d680 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1d690 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1d6a0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1d6b0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1d6c0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1d6d0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1d6e0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1d6f0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1d700 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1d710 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1d720 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1d730 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d740 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1d750 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1d760 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1d770 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1d780 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1d790 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1d7a0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1d7b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1d7c0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1d7d0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1d7e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d7f0 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1d800 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d810 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1d820 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1d830 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1d840 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1d850 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1d860 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1d870 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1d880 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1d890 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d8a0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1d8b0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1d8c0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1d8d0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1d8e0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1d8f0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1d900 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1d910 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1d920 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1d930 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1d940 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1d950 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1d960 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1d970 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1d980 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1d990 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1d9a0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1d9b0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d9c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1d9d0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1d9e0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d9f0 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1da00 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1da10 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1da20 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1da30 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1da40 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1da50 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1da60 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1da70 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1da80 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1da90 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1daa0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1dab0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1dac0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1dad0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1dae0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1daf0 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1db00 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1db10 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1db20 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1db30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1db40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1db50 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1db60 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1db70 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1db80 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1db90 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1dba0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1dbb0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1dbc0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1dbd0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1dbe0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1dbf0 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1dc00 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1dc10 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1dc20 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1dc30 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1dc40 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1dc50 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1dc60 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1dc70 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1dc80 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1dc90 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1dca0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1dcb0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1dcc0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1dcd0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1dce0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1dcf0 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1dd00 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1dd10 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1dd20 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1dd30 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1dd40 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1dd50 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1dd60 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1dd70 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1dd80 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1dd90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1dda0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1ddb0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1ddc0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1ddd0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1dde0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1ddf0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1de00 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1de10 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1de20 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1de30 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1de40 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1de50 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1de60 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1de70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1de80 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1de90 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1dea0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1deb0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1dec0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1ded0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1dee0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1def0 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1df00 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1df10 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1df20 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1df30 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1df40 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1df50 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1df60 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1df70 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1df80 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1df90 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1dfa0 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1dfb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dfc0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1dfd0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1dfe0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1dff0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1e000 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1e010 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1e020 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1e030 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e040 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1e050 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1e060 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1e070 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1e080 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1e090 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1e0a0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1e0b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1e0c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1e0d0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1e0e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1e0f0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1e100 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1e110 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1e120 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1e130 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1e140 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e150 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1e160 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1e170 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1e180 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e190 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1e1a0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1e1b0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1e1c0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1e1d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1e1e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e1f0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1e200 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e210 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1e220 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1e230 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1e240 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1e250 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1e260 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1e270 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1e280 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1e290 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1e2a0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1e2b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1e2c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e2d0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1e2e0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1e2f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1e300 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1e310 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1e320 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1e330 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1e340 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1e350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1e360 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e370 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1e380 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1e390 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1e3a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e3b0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1e3c0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e3d0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1e3e0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1e3f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1e400 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e410 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1e420 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1e430 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1e440 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1e450 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1e460 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1e470 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1e480 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1e490 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1e4a0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1e4b0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1e4c0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1e4d0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1e4e0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1e4f0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1e500 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1e510 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1e520 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1e530 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1e540 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1e550 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1e560 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1e570 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1e580 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1e590 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1e5a0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1e5b0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1e5c0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1e5d0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1e5e0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1e5f0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1e600 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1e610 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1e620 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1e630 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1e640 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1e650 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1e660 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1e670 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1e680 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1e690 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1e6a0 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1e6b0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1e6c0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1e6d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e6e0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1e6f0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1e700 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1e710 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1e720 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1e730 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1e740 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1e750 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1e760 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1e770 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1e780 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1e790 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1e7a0 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1e7b0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1e7c0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1e7d0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1e7e0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1e7f0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1e800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e810 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1e820 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1e830 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1e840 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1e850 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1e860 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1e870 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1e880 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
1e890 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1e8a0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1e8b0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1e8c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e8d0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1e8e0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1e8f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1e900 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1e910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1e920 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1e930 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e940 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1e950 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1e960 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1e970 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1e980 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1e990 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1e9a0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1e9b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e9c0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1e9d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e9e0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1e9f0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1ea00 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1ea10 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1ea20 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1ea30 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1ea40 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1ea50 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1ea60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1ea70 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1ea80 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1ea90 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1eaa0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1eab0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1eac0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1ead0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1eae0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1eaf0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1eb00 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1eb10 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1eb20 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1eb30 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1eb40 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1eb50 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1eb60 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1eb70 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1eb80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1eb90 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1eba0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1ebb0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1ebc0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1ebd0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1ebe0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1ebf0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1ec00 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1ec10 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1ec20 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1ec30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1ec40 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1ec50 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1ec60 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1ec70 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1ec80 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1ec90 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1eca0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1ecb0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1ecc0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1ecd0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1ece0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1ecf0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1ed00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1ed10 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1ed20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ed30 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1ed40 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1ed50 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1ed60 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1ed70 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1ed80 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1ed90 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1eda0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1edb0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1edc0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1edd0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ede0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1edf0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1ee00 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ee10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ee20 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1ee30 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1ee40 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1ee50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1ee60 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1ee70 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1ee80 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1ee90 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1eea0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1eeb0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1eec0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1eed0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1eee0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1eef0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1ef00 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1ef10 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1ef20 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1ef30 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1ef40 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1ef50 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1ef60 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1ef70 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1ef80 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1ef90 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1efa0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1efb0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1efc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1efd0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1efe0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1eff0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1f000 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1f010 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1f020 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1f030 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1f040 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1f050 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1f060 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1f070 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1f080 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1f090 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1f0a0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1f0b0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1f0c0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1f0d0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1f0e0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1f0f0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1f100 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1f110 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1f120 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1f130 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1f140 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1f150 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1f160 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1f170 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1f180 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1f190 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1f1a0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1f1b0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1f1c0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1f1d0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1f1e0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1f1f0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1f200 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f210 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1f220 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1f230 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1f240 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1f250 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1f260 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1f270 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1f280 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1f290 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1f2a0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1f2b0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1f2c0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1f2d0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1f2e0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1f2f0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1f300 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1f310 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1f320 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1f330 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1f340 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1f350 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1f360 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1f370 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1f380 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1f390 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1f3a0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1f3b0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1f3c0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1f3d0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1f3e0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1f3f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1f400 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1f410 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1f420 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1f430 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f440 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1f450 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1f460 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1f470 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1f480 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1f490 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1f4a0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1f4b0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1f4c0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1f4d0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1f4e0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1f4f0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1f500 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1f510 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1f520 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1f530 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1f540 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1f550 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1f560 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1f570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f580 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1f590 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1f5a0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f5b0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1f5c0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1f5d0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1f5e0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1f5f0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1f600 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1f610 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1f620 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1f630 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1f640 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f650 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1f660 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1f670 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1f680 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f690 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1f6a0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1f6b0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1f6c0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1f6d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f6e0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1f6f0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1f700 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1f710 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1f720 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1f730 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1f740 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1f750 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1f760 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f770 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1f780 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1f790 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1f7a0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1f7b0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1f7c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f7d0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1f7e0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1f7f0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1f800 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1f810 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1f820 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1f830 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1f840 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1f850 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1f860 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1f870 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1f880 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f890 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1f8a0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1f8b0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f8c0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1f8d0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1f8e0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1f8f0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1f900 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1f910 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1f920 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1f930 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1f940 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1f950 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1f960 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1f970 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f980 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1f990 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1f9a0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1f9b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f9c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1f9d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1f9e0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1f9f0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1fa00 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1fa10 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1fa20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1fa30 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1fa40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1fa50 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1fa60 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1fa70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fa80 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1fa90 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1faa0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1fab0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1fac0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1fad0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1fae0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1faf0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1fb00 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1fb10 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1fb20 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1fb30 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1fb40 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fb50 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1fb60 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1fb70 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1fb80 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1fb90 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1fba0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1fbb0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
1fbc0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
1fbd0 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
1fbe0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
1fbf0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1fc00 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1fc10 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1fc20 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1fc30 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1fc40 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1fc50 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1fc60 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1fc70 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1fc80 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1fc90 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1fca0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1fcb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1fcc0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1fcd0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1fce0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1fcf0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1fd00 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1fd10 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1fd20 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1fd30 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1fd40 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1fd50 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1fd60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1fd70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1fd80 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fd90 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1fda0 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1fdb0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1fdc0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1fdd0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1fde0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1fdf0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1fe00 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fe10 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1fe20 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1fe30 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1fe40 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1fe50 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1fe60 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1fe70 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1fe80 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1fe90 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1fea0 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1feb0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1fec0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1fed0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1fee0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1fef0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1ff00 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1ff10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1ff20 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1ff30 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1ff40 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ff50 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1ff60 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1ff70 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1ff80 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1ff90 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1ffa0 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1ffb0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1ffc0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1ffd0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1ffe0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1fff0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
20000 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
20010 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
20020 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
20030 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
20040 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
20050 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
20060 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
20070 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
20080 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20090 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
200a0 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
200b0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
200c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
200d0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
200e0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
200f0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
20100 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
20110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20120 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
20130 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
20140 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20150 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20170 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
20180 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
20190 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
201a0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
201b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
201c0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
201d0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
201e0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
201f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
20210 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
20220 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
20230 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
20240 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20250 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20260 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
20270 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
20280 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
20290 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
202a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
202b0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
202c0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
202d0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
202e0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
202f0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20300 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
20310 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
20320 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20330 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20340 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
20350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
20360 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20370 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20380 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20390 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
203a0 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
203b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
203c0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
203d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
203e0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
203f0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
20400 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20410 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20420 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20430 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
20440 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
20450 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20460 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20470 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20480 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
20490 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
204a0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
204b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
204c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
204d0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
204e0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
204f0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
20500 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20520 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
20530 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
20540 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
20550 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20570 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
20580 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
20590 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
205a0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
205b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
205c0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
205d0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
205e0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
205f0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20610 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
20620 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
20630 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
20640 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
20660 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
20670 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
20680 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
20690 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
206a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
206b0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
206c0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
206d0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
206e0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
206f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
20700 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
20710 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
20720 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
20730 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20740 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
20750 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
20760 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
20770 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
20780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20790 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
207a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
207b0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
207c0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
207d0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
207e0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
207f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20800 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
20810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20830 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
20840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
20850 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
20860 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
20870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20880 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
20890 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
208a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
208b0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
208c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
208d0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
208e0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
208f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20920 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
20930 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
20940 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20950 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20970 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
20980 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
20990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
209a0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
209b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
209c0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
209d0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
209e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
209f0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20a10 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
20a20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
20a30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20a40 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
20a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20a60 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
20a70 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
20a80 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
20a90 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
20aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ab0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
20ac0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
20ad0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
20ae0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20af0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
20b00 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
20b10 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20b20 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
20b30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20b40 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
20b50 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
20b60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
20b70 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
20b80 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
20b90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20ba0 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
20bb0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
20bc0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
20bd0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
20be0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
20bf0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
20c00 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20c10 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20c20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
20c30 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
20c40 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
20c50 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
20c60 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
20c70 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
20c80 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
20c90 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
20ca0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20cb0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
20cc0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
20cd0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
20ce0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
20cf0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
20d00 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
20d10 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
20d20 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
20d30 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
20d40 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
20d50 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
20d60 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
20d70 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
20d80 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
20d90 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
20da0 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
20db0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
20dc0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
20dd0 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
20de0 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
20df0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20e00 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20e10 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20e20 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20e30 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20e40 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20e50 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20e60 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20e70 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20e80 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20e90 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
20ea0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
20eb0 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
20ec0 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20ed0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20ee0 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
20ef0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20f00 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20f10 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20f20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20f30 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20f40 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20f50 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20f60 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20f70 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20f80 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20f90 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
20fa0 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
20fb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
20fc0 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
20fd0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
20fe0 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
20ff0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
21000 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
21010 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
21020 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
21030 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
21040 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
21050 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
21060 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
21070 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
21080 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
21090 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
210a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
210b0 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
210c0 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
210d0 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
210e0 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
210f0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
21100 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
21110 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
21120 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
21130 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
21140 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
21150 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
21160 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
21170 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
21180 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
21190 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
211a0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
211b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
211c0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
211d0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
211e0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
211f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
21200 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
21210 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
21220 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
21230 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
21240 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
21250 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
21260 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
21270 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
21280 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
21290 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
212a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
212b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
212c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
212d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
212e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
212f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
21300 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
21310 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
21320 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
21330 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
21340 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
21350 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
21360 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
21370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
21380 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
21390 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
213a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
213b0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
213c0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
213d0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
213e0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
213f0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
21400 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
21410 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
21420 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
21430 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
21440 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
21450 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
21460 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
21470 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
21480 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
21490 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
214a0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
214b0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
214c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
214d0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
214e0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
214f0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
21500 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
21510 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
21520 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
21530 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
21540 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
21550 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21560 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
21570 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
21580 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
21590 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
215a0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
215b0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
215c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
215d0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
215e0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
215f0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
21600 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
21610 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
21620 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
21630 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
21640 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
21650 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
21660 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
21670 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
21680 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21690 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
216a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
216b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
216c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
216d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
216e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
216f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21700 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
21710 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
21720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21730 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
21740 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
21750 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
21760 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
21770 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
21780 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
21790 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
217a0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
217b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
217c0 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
217d0 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
217e0 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
217f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
21800 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
21810 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
21820 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
21830 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
21840 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
21850 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
21860 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
21870 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
21880 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
21890 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
218a0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
218b0 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
218c0 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
218d0 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
218e0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
218f0 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
21900 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21910 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
21920 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
21930 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
21940 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
21950 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
21960 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
21970 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
21980 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
21990 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
219a0 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
219b0 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
219c0 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
219d0 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
219e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
219f0 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
21a00 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
21a10 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21a20 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
21a30 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
21a40 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
21a50 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
21a60 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
21a70 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
21a80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
21a90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
21aa0 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
21ab0 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
21ac0 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
21ad0 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
21ae0 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
21af0 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
21b00 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
21b10 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
21b20 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
21b30 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
21b40 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
21b50 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
21b60 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
21b70 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
21b80 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
21b90 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
21ba0 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21bb0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
21bc0 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
21bd0 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
21be0 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
21bf0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
21c00 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
21c10 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21c20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
21c30 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
21c40 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
21c50 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
21c60 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
21c70 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
21c80 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21c90 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21ca0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
21cb0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
21cc0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
21cd0 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
21ce0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
21cf0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21d00 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
21d10 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
21d20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
21d30 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
21d40 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
21d50 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
21d60 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
21d70 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
21d80 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
21d90 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
21da0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
21db0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21dc0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
21dd0 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
21de0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
21df0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21e00 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
21e10 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21e20 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
21e30 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
21e40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21e50 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
21e60 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21e70 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
21e80 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21e90 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
21ea0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21eb0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
21ec0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21ed0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
21ee0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21ef0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21f00 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
21f10 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
21f20 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
21f30 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
21f40 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
21f50 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
21f60 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
21f70 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21f80 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21f90 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21fa0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21fb0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
21fc0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
21fd0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21fe0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21ff0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
22000 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22010 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
22020 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
22030 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
22040 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
22050 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
22060 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
22070 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
22080 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22090 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
220a0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
220b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
220c0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
220d0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
220e0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
220f0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
22100 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
22110 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
22120 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
22130 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
22140 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
22150 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
22160 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
22170 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
22180 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
22190 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
221a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
221b0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
221c0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
221d0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
221e0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
221f0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
22200 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22210 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
22220 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
22230 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
22240 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
22250 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
22260 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
22270 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
22280 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
22290 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
222a0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
222b0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
222c0 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
222d0 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
222e0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
222f0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
22300 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
22310 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
22320 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
22330 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
22340 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
22350 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
22360 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
22370 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
22380 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
22390 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
223a0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
223b0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
223c0 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
223d0 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
223e0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
223f0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22400 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
22410 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
22420 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
22430 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
22440 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
22450 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
22460 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
22470 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
22480 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
22490 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
224a0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
224b0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
224c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
224d0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
224e0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
224f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22500 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
22510 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
22520 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
22530 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
22540 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
22550 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
22560 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
22570 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
22580 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
22590 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
225a0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
225b0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
225c0 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
225d0 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
225e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
225f0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
22600 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22610 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
22620 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
22630 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
22640 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
22650 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
22660 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
22670 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
22680 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22690 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
226a0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
226b0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
226c0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
226d0 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
226e0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
226f0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
22700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22710 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
22720 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22730 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
22740 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
22750 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
22760 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
22770 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
22780 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
22790 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
227a0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
227b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
227c0 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
227d0 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
227e0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
227f0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
22800 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
22810 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
22820 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
22830 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
22840 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
22850 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
22860 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
22870 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
22880 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
22890 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
228a0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
228b0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
228c0 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
228d0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
228e0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
228f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22900 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
22910 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
22920 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
22930 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
22940 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
22950 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
22960 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
22970 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
22980 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
22990 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
229a0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
229b0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
229c0 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
229d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
229e0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
229f0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22a00 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
22a10 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22a20 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
22a30 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
22a40 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
22a50 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22a60 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
22a70 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
22a80 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
22a90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
22aa0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
22ab0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
22ac0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
22ad0 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
22ae0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
22af0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22b00 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
22b10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22b20 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
22b30 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22b40 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
22b50 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
22b60 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
22b70 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
22b80 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
22b90 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
22ba0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
22bb0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
22bc0 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
22bd0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22be0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22bf0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
22c00 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
22c10 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
22c20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
22c30 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
22c40 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
22c50 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
22c60 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
22c70 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
22c80 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
22c90 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
22ca0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
22cb0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
22cc0 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
22cd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
22ce0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
22cf0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
22d00 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
22d10 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
22d20 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
22d30 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
22d40 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
22d50 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
22d60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
22d70 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
22d80 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
22d90 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
22da0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
22db0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
22dc0 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
22dd0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22de0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22df0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
22e00 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
22e10 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
22e20 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
22e30 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
22e40 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
22e50 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
22e60 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
22e70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22e80 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
22e90 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
22ea0 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
22eb0 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
22ec0 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
22ed0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
22ee0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
22ef0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
22f00 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
22f10 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
22f20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22f30 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
22f40 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
22f50 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
22f60 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
22f70 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
22f80 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
22f90 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
22fa0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
22fb0 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
22fc0 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
22fd0 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
22fe0 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
22ff0 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
23000 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
23010 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
23020 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
23030 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
23040 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
23050 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
23060 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
23070 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
23080 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
23090 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
230a0 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
230b0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
230c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
230d0 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
230e0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
230f0 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
23100 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
23110 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
23120 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
23130 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
23140 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
23150 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
23160 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
23170 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
23180 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
23190 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
231a0 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
231b0 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
231c0 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
231d0 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
231e0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
231f0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
23200 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
23210 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
23220 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
23230 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
23240 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
23250 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
23260 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
23270 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
23280 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
23290 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
232a0 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
232b0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
232c0 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
232d0 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
232e0 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
232f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
23300 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
23310 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
23320 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
23330 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
23340 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
23350 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
23360 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
23370 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
23380 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
23390 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
233a0 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
233b0 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
233c0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
233d0 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
233e0 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
233f0 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
23400 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
23410 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
23420 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
23430 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
23440 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
23450 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
23460 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
23470 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
23480 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
23490 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
234a0 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
234b0 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
234c0 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
234d0 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
234e0 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
234f0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
23500 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
23510 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
23520 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
23530 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
23540 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
23550 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
23560 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
23570 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
23580 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
23590 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
235a0 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
235b0 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
235c0 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
235d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
235e0 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
235f0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
23600 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
23610 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
23620 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
23630 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
23640 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
23650 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
23660 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
23670 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23680 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
23690 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
236a0 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
236b0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
236c0 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
236d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
236e0 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
236f0 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
23700 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
23710 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
23720 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
23730 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
23740 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
23750 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
23760 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
23770 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
23780 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
23790 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
237a0 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
237b0 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
237c0 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
237d0 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
237e0 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
237f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23800 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
23810 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23820 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
23830 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
23840 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
23850 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
23860 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
23870 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
23880 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
23890 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
238a0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
238b0 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
238c0 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
238d0 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
238e0 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
238f0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
23900 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
23910 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
23920 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
23930 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
23940 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
23950 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
23960 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
23970 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
23980 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
23990 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
239a0 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
239b0 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
239c0 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
239d0 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
239e0 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
239f0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
23a00 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
23a10 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
23a20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
23a30 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
23a40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
23a50 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
23a60 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
23a70 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
23a80 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
23a90 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
23aa0 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
23ab0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
23ac0 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
23ad0 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
23ae0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
23af0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
23b00 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
23b10 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
23b20 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
23b30 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
23b40 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
23b50 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
23b60 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
23b70 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
23b80 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
23b90 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
23ba0 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
23bb0 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
23bc0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23bd0 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
23be0 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
23bf0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
23c00 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
23c10 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
23c20 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
23c30 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
23c40 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
23c50 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
23c60 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
23c70 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
23c80 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
23c90 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
23ca0 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
23cb0 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
23cc0 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
23cd0 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
23ce0 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
23cf0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
23d00 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
23d10 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
23d20 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
23d30 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
23d40 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
23d50 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
23d60 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
23d70 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
23d80 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
23d90 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23da0 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
23db0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
23dc0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
23dd0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
23de0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
23df0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
23e00 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
23e10 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
23e20 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23e30 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
23e40 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
23e50 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
23e60 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
23e70 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
23e80 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
23e90 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
23ea0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
23eb0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23ec0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23ed0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23ee0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23ef0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23f00 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23f10 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
23f20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
23f30 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23f40 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
23f50 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
23f60 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
23f70 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
23f80 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23f90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23fa0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
23fb0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
23fc0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
23fd0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
23fe0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23ff0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
24000 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
24010 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
24020 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
24030 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
24040 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
24050 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
24060 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
24070 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
24080 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
24090 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
240a0 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
240b0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
240c0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
240d0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
240e0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
240f0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
24100 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
24110 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
24120 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
24130 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
24140 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
24150 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
24160 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
24170 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
24180 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
24190 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
241a0 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
241b0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
241c0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
241d0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
241e0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
241f0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
24200 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
24210 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
24220 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
24230 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
24240 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
24250 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
24260 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
24270 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
24280 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
24290 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
242a0 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
242b0 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
242c0 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
242d0 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
242e0 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
242f0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
24300 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
24310 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
24320 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
24330 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
24340 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
24350 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
24360 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
24370 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
24380 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
24390 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
243a0 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
243b0 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
243c0 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
243d0 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
243e0 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
243f0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
24400 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
24410 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
24420 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
24430 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
24440 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
24450 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
24460 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
24470 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
24480 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
24490 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
244a0 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
244b0 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
244c0 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
244d0 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
244e0 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
244f0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
24500 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
24510 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
24520 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
24530 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
24540 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
24550 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
24560 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
24570 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
24580 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
24590 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
245a0 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
245b0 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
245c0 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
245d0 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
245e0 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
245f0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
24600 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
24610 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
24620 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
24630 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
24640 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
24650 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
24660 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
24670 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
24680 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
24690 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
246a0 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
246b0 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
246c0 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
246d0 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
246e0 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
246f0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
24700 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
24710 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
24720 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
24730 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
24740 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
24750 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
24760 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
24770 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
24780 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
24790 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
247a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
247b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
247c0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
247d0 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
247e0 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
247f0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
24800 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
24810 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
24820 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
24830 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
24840 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
24850 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
24860 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
24870 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
24880 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
24890 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
248a0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
248b0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
248c0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
248d0 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
248e0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
248f0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24900 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24910 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24920 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
24930 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24940 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24950 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24960 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
24970 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
24980 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
24990 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
249a0 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
249b0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
249c0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
249d0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
249e0 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
249f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24a00 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
24a10 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
24a20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
24a30 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
24a40 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
24a50 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
24a60 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
24a70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
24a80 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
24a90 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
24aa0 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
24ab0 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
24ac0 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
24ad0 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
24ae0 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
24af0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
24b00 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
24b10 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
24b20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
24b30 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
24b40 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
24b50 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
24b60 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24b70 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
24b80 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24b90 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
24ba0 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
24bb0 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
24bc0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24bd0 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
24be0 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
24bf0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
24c00 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
24c10 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
24c20 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
24c30 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
24c40 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
24c50 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
24c60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
24c70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
24c80 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
24c90 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
24ca0 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
24cb0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
24cc0 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
24cd0 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
24ce0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24cf0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
24d00 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24d10 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
24d20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
24d30 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
24d40 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
24d50 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
24d60 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
24d70 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
24d80 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
24d90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24da0 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
24db0 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
24dc0 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
24dd0 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
24de0 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
24df0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
24e00 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
24e10 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
24e20 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24e30 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
24e40 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
24e50 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
24e60 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
24e70 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
24e80 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
24e90 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
24ea0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
24eb0 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
24ec0 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
24ed0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
24ee0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24ef0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
24f00 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
24f10 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
24f20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24f30 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
24f40 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
24f50 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
24f60 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
24f70 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
24f80 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
24f90 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
24fa0 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
24fb0 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
24fc0 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
24fd0 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
24fe0 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
24ff0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
25000 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
25010 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
25020 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
25030 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
25040 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
25050 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
25060 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
25070 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
25080 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
25090 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
250a0 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
250b0 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
250c0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
250d0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
250e0 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
250f0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
25100 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
25110 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
25120 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
25130 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
25140 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
25150 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
25160 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25170 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
25180 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
25190 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
251a0 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
251b0 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
251c0 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
251d0 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
251e0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
251f0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
25200 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
25210 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
25220 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
25230 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
25240 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
25250 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
25260 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
25270 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
25280 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
25290 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
252a0 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
252b0 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
252c0 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
252d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
252e0 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
252f0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
25300 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
25310 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
25320 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
25330 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
25340 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
25350 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
25360 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25370 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
25380 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
25390 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
253a0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
253b0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
253c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
253d0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
253e0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
253f0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
25400 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
25410 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
25420 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
25430 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
25440 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
25450 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
25460 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
25470 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
25480 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
25490 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
254a0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
254b0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
254c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
254d0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
254e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
254f0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
25500 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
25510 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
25520 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
25530 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
25540 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
25550 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
25560 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
25570 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
25580 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
25590 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
255a0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
255b0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
255c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
255d0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
255e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
255f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25600 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25610 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
25620 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
25630 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
25640 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25650 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
25660 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
25670 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
25680 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
25690 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
256a0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
256b0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
256c0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
256d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
256e0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
256f0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
25700 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
25710 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
25720 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25730 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
25740 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
25750 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
25760 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
25770 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
25780 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
25790 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
257a0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
257b0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
257c0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
257d0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
257e0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
257f0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
25800 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25810 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
25820 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
25830 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
25840 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
25850 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
25860 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
25870 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
25880 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
25890 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
258a0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
258b0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
258c0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
258d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
258e0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
258f0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
25900 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
25910 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
25920 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
25930 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
25940 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
25950 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
25960 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
25970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25980 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
25990 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
259a0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
259b0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
259c0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
259d0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
259e0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
259f0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25a00 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
25a10 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
25a20 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
25a30 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
25a40 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
25a50 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
25a60 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
25a70 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
25a80 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
25a90 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
25aa0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
25ab0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
25ac0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
25ad0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
25ae0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
25af0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
25b00 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
25b10 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
25b20 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
25b30 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
25b40 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
25b50 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
25b60 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
25b70 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
25b80 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
25b90 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
25ba0 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
25bb0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25bc0 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
25bd0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25be0 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
25bf0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
25c00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
25c10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
25c20 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
25c30 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
25c40 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
25c50 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
25c60 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
25c70 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
25c80 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
25c90 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
25ca0 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
25cb0 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
25cc0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
25cd0 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
25ce0 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
25cf0 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
25d00 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
25d10 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
25d20 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
25d30 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
25d40 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
25d50 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
25d60 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
25d70 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
25d80 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
25d90 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
25da0 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
25db0 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
25dc0 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
25dd0 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
25de0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25df0 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
25e00 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
25e10 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
25e20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25e30 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25e40 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
25e50 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
25e60 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
25e70 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
25e80 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
25e90 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
25ea0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
25eb0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
25ec0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
25ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25ee0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
25ef0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
25f00 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25f10 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
25f20 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25f30 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
25f40 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
25f50 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
25f60 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
25f70 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
25f80 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
25f90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25fa0 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
25fb0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
25fc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25fd0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25fe0 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25ff0 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
26000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
26010 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
26020 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
26030 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
26040 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26050 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
26060 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
26070 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
26080 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
26090 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
260a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
260b0 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
260c0 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
260d0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
260e0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
260f0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
26100 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
26110 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
26120 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
26130 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
26140 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
26150 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
26160 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
26170 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
26180 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
26190 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
261a0 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
261b0 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
261c0 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
261d0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
261e0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
261f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
26200 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
26210 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
26220 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
26230 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
26240 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
26250 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
26260 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
26270 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
26280 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
26290 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
262a0 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
262b0 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
262c0 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
262d0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
262e0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
262f0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
26300 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
26310 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
26320 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
26330 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
26340 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
26350 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
26360 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
26370 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
26380 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
26390 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
263a0 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
263b0 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
263c0 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
263d0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
263e0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
263f0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
26400 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
26410 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
26420 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
26430 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
26440 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
26450 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
26460 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
26470 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
26480 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
26490 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
264a0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
264b0 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
264c0 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
264d0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
264e0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
264f0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
26500 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
26510 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
26520 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
26530 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
26540 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
26550 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
26560 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
26570 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
26580 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
26590 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
265a0 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
265b0 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
265c0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
265d0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
265e0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
265f0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
26600 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
26610 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
26620 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
26630 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
26640 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
26650 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
26660 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
26670 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
26680 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
26690 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
266a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
266b0 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
266c0 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
266d0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
266e0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
266f0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
26700 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
26710 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
26720 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
26730 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
26740 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
26750 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
26760 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
26770 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
26780 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
26790 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
267a0 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
267b0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
267c0 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
267d0 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
267e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
267f0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
26800 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
26810 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
26820 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
26830 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
26840 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
26850 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
26860 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
26870 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
26880 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
26890 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
268a0 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
268b0 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
268c0 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
268d0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
268e0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
268f0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
26900 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
26910 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
26920 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
26930 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
26940 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
26950 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
26960 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26970 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
26980 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26990 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
269a0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
269b0 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
269c0 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
269d0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
269e0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
269f0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26a00 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
26a10 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26a20 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
26a30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
26a40 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
26a50 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26a60 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
26a70 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
26a80 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
26a90 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26aa0 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
26ab0 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
26ac0 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
26ad0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
26ae0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
26af0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
26b00 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26b10 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
26b20 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
26b30 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
26b40 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
26b50 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26b60 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
26b70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26b80 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
26b90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26ba0 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
26bb0 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
26bc0 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
26bd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26be0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26bf0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
26c00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
26c10 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
26c20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26c30 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
26c40 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
26c50 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
26c60 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
26c70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26c80 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
26c90 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26ca0 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
26cb0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26cc0 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
26cd0 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
26ce0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
26cf0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
26d00 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
26d10 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
26d20 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
26d30 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
26d40 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
26d50 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
26d60 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
26d70 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
26d80 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
26d90 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26da0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
26db0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26dc0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
26dd0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26de0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26df0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
26e00 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
26e10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26e20 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
26e30 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26e40 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
26e50 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26e60 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26e70 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
26e80 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
26e90 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
26ea0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26eb0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
26ec0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
26ed0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26ee0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
26ef0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26f00 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
26f10 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
26f20 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
26f30 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
26f40 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
26f50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26f60 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
26f70 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26f90 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
26fa0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26fb0 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
26fc0 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
26fd0 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
26fe0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
26ff0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27000 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
27010 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27020 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
27030 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27040 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
27050 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
27060 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
27070 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27080 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
27090 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
270a0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
270b0 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
270c0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
270d0 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
270e0 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
270f0 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
27100 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
27110 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
27120 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
27130 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
27140 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
27150 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27160 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
27170 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
27180 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
27190 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
271a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
271b0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
271c0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
271d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
271e0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
271f0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
27200 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27210 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
27220 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
27230 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27240 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
27250 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
27260 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27270 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
27280 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
27290 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
272a0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
272b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
272c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
272d0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
272e0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
272f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27300 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27310 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
27320 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
27330 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27340 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
27350 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
27360 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
27370 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
27380 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
27390 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
273a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
273b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
273c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
273d0 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
273e0 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
273f0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
27400 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
27410 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
27420 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
27430 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
27440 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
27450 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
27460 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
27470 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
27480 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27490 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
274a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
274b0 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
274c0 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
274d0 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
274e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
274f0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
27500 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
27510 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
27520 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
27530 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
27540 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
27550 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
27560 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
27570 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
27580 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
27590 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
275a0 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
275b0 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
275c0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
275d0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
275e0 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
275f0 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
27600 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
27610 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
27620 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
27630 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
27640 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
27650 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
27660 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
27670 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
27680 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
27690 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
276a0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
276b0 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
276c0 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
276d0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
276e0 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
276f0 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
27700 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
27710 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
27720 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
27730 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
27740 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
27750 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
27760 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
27770 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
27780 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
27790 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
277a0 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
277b0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
277c0 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
277d0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
277e0 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
277f0 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
27800 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
27810 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
27820 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
27830 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
27840 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
27850 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
27860 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
27870 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
27880 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
27890 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
278a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
278b0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
278c0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
278d0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
278e0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
278f0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
27900 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
27910 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
27920 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
27930 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
27940 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
27950 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
27960 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
27970 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
27980 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
27990 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
279a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
279b0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
279c0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
279d0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
279e0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
279f0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
27a00 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
27a10 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
27a20 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
27a30 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
27a40 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
27a50 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
27a60 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
27a70 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
27a80 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27a90 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
27aa0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
27ab0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
27ac0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
27ad0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
27ae0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
27af0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
27b00 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
27b10 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
27b20 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
27b30 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
27b40 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
27b50 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
27b60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
27b70 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
27b80 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
27b90 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
27ba0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
27bb0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
27bc0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
27bd0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
27be0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
27bf0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
27c00 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
27c10 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
27c20 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
27c30 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
27c40 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
27c50 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
27c60 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
27c70 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
27c80 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
27c90 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
27ca0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
27cb0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
27cc0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
27cd0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
27ce0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
27cf0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
27d00 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
27d10 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
27d20 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
27d30 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
27d40 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
27d50 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
27d60 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
27d70 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
27d80 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
27d90 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
27da0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
27db0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
27dc0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
27dd0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
27de0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
27df0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
27e00 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
27e10 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
27e20 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
27e30 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
27e40 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
27e50 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
27e60 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
27e70 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
27e80 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
27e90 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
27ea0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
27eb0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
27ec0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27ed0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
27ee0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
27ef0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
27f00 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
27f10 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
27f20 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
27f30 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
27f40 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
27f50 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
27f60 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
27f70 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27f80 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
27f90 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
27fa0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
27fb0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
27fc0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
27fd0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
27fe0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
27ff0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
28000 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
28010 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
28020 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
28030 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
28040 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
28050 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
28060 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
28070 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
28080 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
28090 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
280a0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
280b0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
280c0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
280d0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
280e0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
280f0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
28100 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
28110 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
28120 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
28130 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
28140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
28150 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
28160 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
28170 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
28180 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
28190 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
281a0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
281b0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
281c0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
281d0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
281e0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
281f0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
28200 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
28210 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
28220 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
28230 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
28240 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
28250 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
28260 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
28270 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
28280 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
28290 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
282a0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
282b0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
282c0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
282d0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
282e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
282f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28300 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28310 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28320 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
28330 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28340 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
28350 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28360 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28370 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28380 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28390 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
283a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
283b0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
283c0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
283d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
283e0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
283f0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28400 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28410 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
28420 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28430 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
28440 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28450 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28460 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
28470 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
28480 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28490 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
284a0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
284b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
284c0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
284d0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
284e0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
284f0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28500 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28510 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28520 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
28530 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28540 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28550 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28560 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
28570 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
28580 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28590 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
285a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
285b0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
285c0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
285d0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
285e0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
285f0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28600 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28610 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28620 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28630 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28640 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28650 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28660 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
28670 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28680 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28690 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
286a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
286b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
286c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
286d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
286e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
286f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28700 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28710 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28720 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28730 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28740 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28750 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28760 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28770 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28780 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28790 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
287a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
287b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
287c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
287d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
287e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
287f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28800 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
28810 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
28820 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
28830 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
28840 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
28850 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
28860 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
28870 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
28880 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
28890 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
288a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
288b0 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
288c0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
288d0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
288e0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
288f0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28900 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28910 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
28920 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
28930 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
28940 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
28950 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
28960 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
28970 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
28980 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
28990 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
289a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
289b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
289c0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
289d0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
289e0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
289f0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
28a00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28a10 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
28a20 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
28a30 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
28a40 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28a50 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
28a60 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
28a70 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
28a80 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
28a90 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
28aa0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
28ab0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
28ac0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
28ad0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
28ae0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
28af0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
28b00 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
28b10 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
28b20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
28b30 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
28b40 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
28b50 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
28b60 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
28b70 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
28b80 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
28b90 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
28ba0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
28bb0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
28bc0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
28bd0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
28be0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
28bf0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
28c00 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
28c10 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
28c20 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28c30 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
28c40 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
28c50 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
28c60 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
28c70 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
28c80 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
28c90 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
28ca0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
28cb0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
28cc0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
28cd0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
28ce0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
28cf0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28d00 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
28d10 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
28d20 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
28d30 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
28d40 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
28d50 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
28d60 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
28d70 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
28d80 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
28d90 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
28da0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
28db0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
28dc0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
28dd0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
28de0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
28df0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
28e00 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
28e10 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
28e20 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
28e30 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
28e40 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
28e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
28e60 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
28e70 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
28e80 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28e90 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28ea0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
28eb0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
28ec0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
28ed0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28ee0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28ef0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
28f00 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28f10 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
28f20 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28f30 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28f40 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28f50 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
28f60 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28f70 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
28f80 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28f90 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
28fa0 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
28fb0 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
28fc0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28fd0 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
28fe0 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
28ff0 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
29000 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
29010 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
29020 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
29030 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
29040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
29050 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
29060 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
29070 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
29080 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
29090 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
290a0 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
290b0 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
290c0 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
290d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
290e0 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
290f0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
29100 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
29110 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29120 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
29130 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
29140 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
29150 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
29160 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
29170 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
29180 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
29190 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
291a0 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
291b0 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
291c0 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
291d0 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
291e0 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
291f0 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
29200 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
29210 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
29220 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
29230 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
29240 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
29250 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
29260 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
29270 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
29280 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29290 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
292a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
292b0 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
292c0 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
292d0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
292e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
292f0 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
29300 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29310 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
29320 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
29330 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29340 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
29350 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
29360 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
29370 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
29380 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
29390 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
293a0 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
293b0 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
293c0 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
293d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
293e0 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
293f0 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
29400 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
29410 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
29420 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
29430 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29440 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
29450 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
29460 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
29470 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
29480 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
29490 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
294a0 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
294b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
294c0 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
294d0 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
294e0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
294f0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
29500 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
29510 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
29520 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
29530 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
29540 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
29550 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
29560 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29570 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
29580 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
29590 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
295a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
295b0 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
295c0 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
295d0 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
295e0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
295f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
29600 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
29610 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
29620 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
29630 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
29640 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
29650 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
29660 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
29670 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
29680 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
29690 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
296a0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
296b0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
296c0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
296d0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
296e0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
296f0 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
29700 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
29710 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
29720 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
29730 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
29740 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
29750 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
29760 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
29770 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
29780 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
29790 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
297a0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
297b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
297c0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
297d0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
297e0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
297f0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
29800 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
29810 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29820 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
29830 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
29840 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
29850 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
29860 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
29870 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
29880 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
29890 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
298a0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
298b0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
298c0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
298d0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
298e0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
298f0 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
29900 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
29910 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29920 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29930 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
29940 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
29950 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
29960 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
29970 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
29980 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29990 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
299a0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
299b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
299c0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
299d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
299e0 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
299f0 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
29a00 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29a10 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
29a20 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
29a30 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
29a40 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
29a50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
29a60 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
29a70 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
29a80 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
29a90 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
29aa0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
29ab0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
29ac0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29ad0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
29ae0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
29af0 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
29b00 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
29b10 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
29b20 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
29b30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
29b40 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
29b50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
29b60 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
29b70 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
29b80 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
29b90 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
29ba0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
29bb0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
29bc0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
29bd0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
29be0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
29bf0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
29c00 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
29c10 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
29c20 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
29c30 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
29c40 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
29c50 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
29c60 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
29c70 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
29c80 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
29c90 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
29ca0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
29cb0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
29cc0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
29cd0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
29ce0 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
29cf0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
29d00 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
29d10 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29d20 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
29d30 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
29d40 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
29d50 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
29d60 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
29d70 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
29d80 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
29d90 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
29da0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
29db0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
29dc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
29dd0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
29de0 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
29df0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
29e00 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
29e10 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
29e20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
29e30 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
29e40 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
29e50 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
29e60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29e70 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
29e80 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
29e90 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
29ea0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
29eb0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
29ec0 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
29ed0 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
29ee0 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
29ef0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
29f00 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
29f10 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
29f20 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
29f30 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
29f40 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
29f50 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
29f60 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
29f70 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
29f80 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
29f90 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
29fa0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
29fb0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
29fc0 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
29fd0 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
29fe0 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
29ff0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2a000 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2a010 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2a020 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2a030 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2a040 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2a050 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2a060 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2a070 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2a080 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2a090 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2a0a0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2a0b0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2a0c0 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2a0d0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2a0e0 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2a0f0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2a100 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2a110 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2a120 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2a130 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2a140 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2a150 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2a160 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2a170 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2a180 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2a190 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2a1a0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2a1b0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2a1c0 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2a1d0 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2a1e0 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2a1f0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2a200 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2a210 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2a220 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2a230 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2a240 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a250 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2a260 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2a270 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2a280 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2a290 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2a2a0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2a2b0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2a2c0 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2a2d0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2a2e0 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2a2f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a300 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2a310 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2a320 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2a330 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2a340 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2a350 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2a360 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2a370 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2a380 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a390 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a3a0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2a3b0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2a3c0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2a3d0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2a3e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a3f0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2a400 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2a410 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2a420 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2a430 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2a440 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2a450 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2a460 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2a470 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2a480 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a490 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2a4a0 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2a4b0 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2a4c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2a4d0 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2a4e0 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2a4f0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2a500 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2a510 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2a520 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a530 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2a540 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2a550 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2a560 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2a570 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2a580 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2a590 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2a5a0 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2a5b0 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2a5c0 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2a5d0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2a5e0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2a5f0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2a600 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2a610 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2a620 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2a630 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2a640 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2a650 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2a660 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2a670 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2a680 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2a690 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a6a0 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2a6b0 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2a6c0 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2a6d0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2a6e0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2a6f0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2a700 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2a710 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2a720 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2a730 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2a740 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2a750 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2a760 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2a770 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a780 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2a790 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2a7a0 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2a7b0 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2a7c0 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2a7d0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2a7e0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2a7f0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2a800 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2a810 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2a820 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2a830 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2a840 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2a850 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2a860 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2a870 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2a880 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2a890 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2a8a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2a8b0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2a8c0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2a8d0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2a8e0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2a8f0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2a900 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2a910 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2a920 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2a930 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2a940 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2a950 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2a960 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2a970 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2a980 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2a990 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2a9a0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2a9b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2a9c0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2a9d0 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a9e0 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2a9f0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2aa00 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2aa10 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2aa20 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2aa30 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2aa40 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2aa50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2aa60 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2aa70 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2aa80 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2aa90 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2aaa0 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2aab0 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2aac0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2aad0 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2aae0 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2aaf0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2ab00 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2ab10 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2ab20 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2ab30 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2ab40 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2ab50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2ab60 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2ab70 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2ab80 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2ab90 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2aba0 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2abb0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2abc0 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2abd0 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2abe0 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2abf0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2ac00 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2ac10 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2ac20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ac30 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2ac40 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2ac50 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2ac60 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2ac70 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2ac80 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2ac90 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2aca0 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2acb0 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2acc0 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2acd0 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2ace0 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2acf0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2ad00 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2ad10 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2ad20 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2ad30 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2ad40 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2ad50 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2ad60 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2ad70 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2ad80 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2ad90 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2ada0 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2adb0 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2adc0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2add0 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2ade0 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2adf0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ae00 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2ae10 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2ae20 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2ae30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ae40 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2ae50 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2ae60 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2ae70 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ae80 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2ae90 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2aea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2aeb0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2aec0 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2aed0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2aee0 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2aef0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2af00 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2af10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2af20 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2af30 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2af40 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2af50 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2af60 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2af70 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2af80 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2af90 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2afa0 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2afb0 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2afc0 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2afd0 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2afe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2aff0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2b000 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2b010 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2b020 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2b030 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2b040 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2b050 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2b060 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2b070 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2b080 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2b090 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2b0a0 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2b0b0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2b0c0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2b0d0 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2b0e0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2b0f0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2b100 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2b110 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2b120 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2b130 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2b140 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2b150 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2b160 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2b170 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b180 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b190 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2b1a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2b1b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2b1c0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2b1d0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b1e0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2b1f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2b200 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2b210 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2b220 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2b230 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2b240 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2b250 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2b260 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2b270 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2b280 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2b290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2b2a0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2b2b0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2b2c0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2b2d0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2b2e0 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2b2f0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2b300 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2b310 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b320 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2b330 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2b340 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2b350 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2b360 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2b370 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2b380 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2b390 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b3a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2b3b0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2b3c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b3d0 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2b3e0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b3f0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2b400 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b410 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b420 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2b430 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b440 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2b450 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2b460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b470 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b480 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2b490 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2b4a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b4b0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2b4c0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2b4d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2b4e0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2b4f0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2b500 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2b510 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2b520 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2b530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b540 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2b550 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2b560 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b570 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2b580 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b590 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b5a0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2b5b0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2b5c0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2b5d0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2b5e0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2b5f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2b600 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2b610 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2b620 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2b630 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2b640 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2b650 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2b660 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2b670 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2b680 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b690 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2b6a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2b6b0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2b6c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2b6d0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2b6e0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2b6f0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2b700 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2b710 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2b720 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2b730 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2b740 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2b750 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2b760 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2b770 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2b780 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2b790 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2b7a0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2b7b0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2b7c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b7d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b7e0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2b7f0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b800 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2b810 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2b820 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b830 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b840 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2b850 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b860 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2b870 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b880 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2b890 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2b8a0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b8b0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b8c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2b8d0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2b8e0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b8f0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2b900 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2b910 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2b920 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b930 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2b940 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2b950 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2b960 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2b970 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2b980 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2b990 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2b9a0 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2b9b0 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2b9c0 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2b9d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2b9e0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2b9f0 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2ba00 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2ba10 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2ba20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2ba30 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2ba40 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2ba50 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2ba60 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2ba70 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2ba80 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2ba90 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2baa0 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2bab0 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2bac0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2bad0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2bae0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2baf0 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2bb00 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2bb10 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2bb20 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2bb30 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2bb40 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2bb50 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2bb60 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2bb70 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2bb80 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2bb90 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2bba0 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2bbb0 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2bbc0 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2bbd0 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2bbe0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2bbf0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2bc00 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2bc10 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2bc20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bc30 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bc40 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2bc50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bc60 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2bc70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bc80 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2bc90 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2bca0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bcb0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2bcc0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2bcd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bce0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2bcf0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2bd00 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
2bd10 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2bd20 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2bd30 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2bd40 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2bd50 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2bd60 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2bd70 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2bd80 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2bd90 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2bda0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2bdb0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2bdc0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2bdd0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2bde0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2bdf0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2be00 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2be10 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2be20 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2be30 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2be40 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2be50 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2be60 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2be70 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2be80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2be90 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2bea0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2beb0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2bec0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2bed0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bee0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2bef0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2bf00 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bf10 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 69  er_name()]..*/.i
2bf20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2bf30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bf40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2bf50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2bf60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bf70 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2bf80 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2bf90 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2bfa0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2bfb0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2bfc0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2bfd0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2bfe0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2bff0 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2c000 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2c010 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2c020 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2c030 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c040 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2c050 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2c060 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2c070 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2c080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65  .int sqlite3_cle
2c090 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
2c0a0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2c0b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2c0c0 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
2c0d0 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
2c0e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c0f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2c100 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
2c110 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2c120 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
2c130 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
2c140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c150 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
2c160 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2c170 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
2c180 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
2c190 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
2c1a0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
2c1b0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
2c1c0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
2c1d0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
2c1e0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2c1f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c200 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2c210 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2c220 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
2c230 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
2c240 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54  esult Set.** MET
2c250 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c260 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2c270 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2c280 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
2c290 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
2c2a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
2c2b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2c2c0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2c2d0 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
2c2e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2c2f0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
2c300 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
2c310 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
2c320 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
2c330 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
2c340 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2c350 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
2c360 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
2c370 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
2c380 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2c390 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
2c3a0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
2c3b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2c3c0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
2c3d0 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
2c3e0 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
2c3f0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2c400 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
2c410 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
2c420 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
2c430 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
2c440 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2c450 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
2c460 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
2c470 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
2c480 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
2c490 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
2c4a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c4b0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
2c4c0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75   statement is au
2c4d0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72  tomatically.** r
2c4e0 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65  eprepared by the
2c4f0 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b   first call to [
2c500 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c510 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
2c520 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c   run.** or until
2c530 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74   the next call t
2c540 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
2c550 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71  umn_name() or sq
2c560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c570 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d  e16() on the sam
2c580 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  e column..**.** 
2c590 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ^If sqlite3_mall
2c5a0 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e  oc() fails durin
2c5b0 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67  g the processing
2c5c0 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69   of either routi
2c5d0 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70  ne.** (for examp
2c5e0 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76  le during a conv
2c5f0 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d  ersion from UTF-
2c600 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65  8 to UTF-16) the
2c610 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
2c620 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2c630 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2c640 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c   of a result col
2c650 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65  umn is the value
2c660 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61   of the "AS" cla
2c670 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20  use for.** that 
2c680 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65  column, if there
2c690 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65   is an AS clause
2c6a0 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
2c6b0 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74  o AS clause.** t
2c6c0 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  hen the name of 
2c6d0 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e  the column is un
2c6e0 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61  specified and ma
2c6f0 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a  y change from.**
2c700 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20   one release of 
2c710 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65  SQLite to the ne
2c720 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  xt..*/.const cha
2c730 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2c740 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  n_name(sqlite3_s
2c750 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f  tmt*, int N);.co
2c760 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c770 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2c780 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c790 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2c7a0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2c7b0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2c7c0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2c7d0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2c7e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2c7f0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2c800 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2c810 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2c820 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2c830 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2c840 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2c850 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2c860 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2c870 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2c880 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2c890 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2c8a0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2c8b0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2c8c0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2c8d0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2c8e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2c8f0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2c900 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2c910 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2c920 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2c930 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2c940 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2c950 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2c960 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2c970 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2c980 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2c990 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2c9a0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2c9b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c9c0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2c9d0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2c9e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2c9f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2ca00 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2ca10 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2ca20 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2ca30 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2ca40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2ca50 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2ca60 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2ca70 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2ca80 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2ca90 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2caa0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2cab0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2cac0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2cad0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2cae0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2caf0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2cb00 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2cb10 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2cb20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2cb30 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2cb40 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2cb50 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2cb60 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2cb70 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2cb80 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2cb90 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2cba0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2cbb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2cbc0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2cbd0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2cbe0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2cbf0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2cc00 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2cc10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2cc20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2cc30 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2cc40 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2cc50 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2cc60 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2cc70 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2cc80 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2cc90 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2cca0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2ccb0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2ccc0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2ccd0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2cce0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2ccf0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2cd00 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2cd10 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2cd20 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2cd30 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2cd40 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2cd50 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2cd60 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2cd70 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2cd80 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2cd90 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2cda0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2cdb0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2cdc0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2cdd0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2cde0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2cdf0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2ce00 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2ce10 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2ce20 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2ce30 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2ce40 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2ce50 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2ce60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2ce70 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2ce80 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2ce90 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2cea0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2ceb0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2cec0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2ced0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2cee0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2cef0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2cf00 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2cf10 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2cf20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2cf30 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2cf40 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2cf50 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2cf60 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2cf70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2cf80 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2cf90 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2cfa0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2cfb0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2cfc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2cfd0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2cfe0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2cff0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d000 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2d010 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
2d020 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2d030 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2d040 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d050 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2d060 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d070 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2d080 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d090 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
2d0a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2d0b0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
2d0c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2d0d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2d0f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2d100 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
2d110 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d120 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
2d130 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d140 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2d150 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d160 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
2d170 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d190 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
2d1a0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
2d1b0 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f   Result.** METHO
2d1c0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2d1d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
2d1e0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
2d1f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d200 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
2d210 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
2d220 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2d230 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
2d240 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
2d250 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
2d260 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
2d270 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
2d280 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
2d290 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2d2a0 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
2d2b0 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
2d2c0 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
2d2d0 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
2d2e0 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
2d2f0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
2d300 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
2d310 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2d320 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
2d330 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
2d340 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
2d350 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2d360 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
2d370 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
2d380 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
2d390 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
2d3a0 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
2d3b0 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
2d3c0 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
2d3d0 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
2d3e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
2d3f0 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
2d400 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
2d410 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
2d420 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
2d430 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
2d440 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
2d450 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
2d460 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
2d470 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
2d480 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
2d490 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
2d4a0 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
2d4b0 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
2d4c0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
2d4d0 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
2d4e0 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
2d4f0 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
2d500 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
2d510 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
2d520 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
2d530 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
2d540 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
2d550 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
2d560 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
2d570 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
2d580 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
2d590 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
2d5a0 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
2d5b0 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
2d5c0 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
2d5d0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
2d5e0 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
2d5f0 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
2d600 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
2d610 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
2d620 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  values..*/.const
2d630 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d640 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73  olumn_decltype(s
2d650 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d660 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d670 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2d680 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2d690 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2d6a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2d6b0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2d6c0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2d6d0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2d6e0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2d6f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d700 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2d710 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2d720 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2d730 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2d740 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d750 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2d760 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2d770 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2d780 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2d790 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2d7a0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2d7b0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2d7c0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2d7d0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2d7e0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2d7f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2d800 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2d810 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2d820 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2d830 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2d840 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2d850 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2d860 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2d870 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2d880 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2d890 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d8a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2d8b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2d8c0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2d8d0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2d8e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d8f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2d900 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2d910 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2d920 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2d930 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2d940 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2d950 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2d960 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2d970 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2d980 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2d990 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2d9a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2d9b0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2d9c0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2d9d0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2d9e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2d9f0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2da00 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2da10 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2da20 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2da30 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2da40 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2da50 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2da60 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2da70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2da80 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2da90 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2daa0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2dab0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2dac0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2dad0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2dae0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2daf0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2db00 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2db10 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2db20 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2db30 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2db40 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2db50 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2db60 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2db70 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2db80 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2db90 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2dba0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2dbb0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2dbc0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2dbd0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2dbe0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2dbf0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2dc00 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2dc10 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2dc20 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2dc30 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2dc40 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2dc50 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2dc60 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2dc70 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2dc80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2dc90 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2dca0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2dcb0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2dcc0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2dcd0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2dce0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2dcf0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2dd00 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2dd10 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2dd20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2dd30 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2dd40 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2dd50 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2dd60 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2dd70 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2dd80 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2dd90 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2dda0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2ddb0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2ddc0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2ddd0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2dde0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2ddf0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2de00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2de10 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2de20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2de30 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2de40 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2de50 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2de60 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2de70 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2de80 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2de90 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2dea0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2deb0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2dec0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2ded0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2dee0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2def0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2df00 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2df10 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2df20 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2df30 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2df40 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2df50 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2df60 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2df70 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2df80 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2df90 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2dfa0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2dfb0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2dfc0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2dfd0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2dfe0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2dff0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2e000 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2e010 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2e020 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2e030 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2e040 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2e050 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2e060 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2e070 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2e080 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2e090 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2e0a0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2e0b0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2e0c0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2e0d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e0e0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2e0f0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2e100 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2e110 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2e120 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2e130 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2e140 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2e150 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2e160 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2e170 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2e180 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2e190 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2e1a0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2e1b0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2e1c0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2e1d0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2e1e0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2e1f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2e200 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2e210 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2e220 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2e230 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e240 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2e250 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2e260 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2e270 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2e280 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2e290 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2e2a0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2e2b0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2e2c0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2e2d0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2e2e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2e2f0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2e300 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2e310 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2e320 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2e330 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2e340 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2e350 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2e360 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2e370 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2e380 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2e390 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2e3a0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2e3b0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2e3c0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2e3d0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2e3e0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2e3f0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2e400 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2e410 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2e420 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2e430 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2e440 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2e450 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2e460 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2e470 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2e480 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2e490 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2e4a0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2e4b0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2e4c0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2e4d0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2e4e0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2e4f0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2e500 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2e510 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2e520 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2e530 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2e540 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2e550 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2e560 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2e570 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2e580 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2e590 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2e5a0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2e5b0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2e5c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2e5d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2e5e0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2e5f0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2e600 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2e610 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2e620 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2e630 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2e640 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2e650 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2e660 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2e670 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2e680 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2e690 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2e6a0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2e6b0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2e6c0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2e6d0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2e6e0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2e6f0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2e700 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2e710 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2e720 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2e730 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2e740 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2e750 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2e760 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2e770 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2e780 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2e790 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2e7a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2e7b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2e7c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2e7d0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2e7e0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e7f0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
2e800 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e810 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
2e820 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
2e830 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
2e840 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2e850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2e860 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2e870 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e880 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2e890 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2e8a0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2e8b0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2e8c0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2e8d0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2e8e0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2e8f0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2e900 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2e910 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2e920 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2e930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2e940 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2e950 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2e960 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2e970 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2e980 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2e990 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2e9a0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2e9b0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2e9c0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2e9d0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e9e0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2e9f0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2ea00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2ea10 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2ea20 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2ea30 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2ea40 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2ea50 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2ea60 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2ea70 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2ea80 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2ea90 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2eaa0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2eab0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2eac0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2ead0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2eae0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2eaf0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2eb00 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2eb10 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2eb20 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2eb30 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2eb40 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2eb50 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2eb60 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2eb70 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2eb80 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2eb90 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )].*/.int sqlite
2eba0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
2ebb0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ebc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ebd0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
2ebe0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
2ebf0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
2ec00 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
2ec10 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
2ec20 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
2ec30 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
2ec40 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
2ec50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
2ec60 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
2ec70 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
2ec80 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
2ec90 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
2eca0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
2ecb0 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
2ecc0 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
2ecd0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
2ece0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
2ecf0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
2ed00 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
2ed10 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
2ed20 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
2ed30 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
2ed40 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
2ed50 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
2ed60 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
2ed70 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
2ed80 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
2ed90 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
2eda0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
2edb0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
2edc0 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
2edd0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
2ede0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
2edf0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2ee00 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
2ee10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
2ee20 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
2ee30 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
2ee40 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
2ee50 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
2ee60 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2ee70 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
2ee80 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
2ee90 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
2eea0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
2eeb0 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
2eec0 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
2eed0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
2eee0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
2eef0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
2ef00 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
2ef10 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
2ef20 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2ef30 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2ef40 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2ef50 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2ef60 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2ef70 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2ef80 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2ef90 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2efa0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2efb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2efc0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2efd0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2efe0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2eff0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2f000 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2f010 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2f020 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2f030 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f040 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2f050 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2f060 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2f070 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2f080 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2f090 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2f0a0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2f0b0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2f0c0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2f0d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2f0e0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2f0f0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2f100 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2f110 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2f120 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2f130 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2f140 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2f150 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2f160 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2f170 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2f180 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2f190 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2f1a0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2f1b0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2f1c0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2f1d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f1e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f1f0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2f200 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2f210 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2f220 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2f230 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2f240 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2f250 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2f260 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f270 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2f280 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2f290 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2f2a0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2f2b0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f2c0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2f2d0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2f2e0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2f2f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f300 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2f310 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2f320 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2f330 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2f340 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2f350 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2f360 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f370 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f380 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2f390 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2f3a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2f3b0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2f3c0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2f3d0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2f3e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2f3f0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2f400 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2f410 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2f420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f430 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f440 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f450 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2f460 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2f470 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2f480 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2f490 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2f4a0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2f4b0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2f4c0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2f4d0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2f4e0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2f4f0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2f500 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2f510 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2f520 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2f530 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2f540 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f550 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2f560 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2f570 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2f580 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2f590 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2f5a0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2f5b0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2f5c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2f5d0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f5e0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2f5f0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2f600 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2f610 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2f620 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
2f630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f640 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2f650 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2f660 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2f670 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2f680 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2f690 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2f6a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6b0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2f6c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f6d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2f6e0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2f6f0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f700 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2f710 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2f720 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f730 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2f740 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2f750 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2f760 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f770 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2f780 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f790 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2f7a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f7b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2f7c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2f7d0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2f7e0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2f7f0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2f800 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2f810 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f820 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2f830 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2f840 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2f850 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f860 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2f870 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2f880 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f890 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2f8a0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2f8b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f8c0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2f8d0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2f8e0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f8f0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2f900 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2f910 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f920 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2f930 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f940 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2f950 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2f960 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2f970 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2f980 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f990 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2f9a0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2f9b0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2f9c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f9d0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2f9e0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f9f0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2fa00 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2fa10 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2fa20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2fa30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fa40 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2fa50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fa60 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2fa70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fa80 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2fa90 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2faa0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2fab0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2fac0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2fad0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2fae0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2faf0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2fb00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2fb10 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2fb20 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2fb30 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2fb40 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2fb50 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2fb60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fb70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2fb80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fb90 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2fba0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2fbb0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2fbc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2fbd0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2fbe0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2fbf0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2fc00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2fc10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fc20 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2fc30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2fc40 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2fc50 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2fc60 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2fc70 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2fc80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2fc90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2fca0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2fcb0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
2fcc0 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
2fcd0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2fce0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2fcf0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2fd00 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2fd10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2fd20 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
2fd30 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
2fd40 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
2fd50 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2fd60 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2fd70 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
2fd80 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
2fd90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2fda0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2fdb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2fdc0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2fdd0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2fde0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2fdf0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2fe00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2fe10 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2fe20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2fe30 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2fe40 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2fe50 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2fe60 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2fe70 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2fe80 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2fe90 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2fea0 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
2feb0 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
2fec0 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
2fed0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2fee0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2fef0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2ff00 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2ff10 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2ff20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2ff30 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2ff40 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2ff50 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2ff60 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2ff70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2ff80 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2ff90 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2ffa0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2ffb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2ffc0 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2ffd0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2ffe0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2fff0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
30000 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
30010 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
30020 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
30030 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
30040 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
30050 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
30060 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
30070 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
30080 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
30090 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
300a0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
300b0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
300c0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
300d0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
300e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
300f0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
30100 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
30110 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30120 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
30130 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
30140 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
30150 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
30160 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
30170 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
30180 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
30190 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
301a0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
301b0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
301c0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
301d0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
301e0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
301f0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
30200 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
30210 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
30220 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
30230 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
30240 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
30250 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
30260 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
30270 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
30280 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
30290 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
302a0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
302b0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
302c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
302d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
302e0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
302f0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
30300 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
30310 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
30320 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
30330 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30340 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
30350 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
30360 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
30370 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30380 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
30390 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
303a0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
303b0 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
303c0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
303d0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
303e0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
303f0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
30400 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
30410 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
30420 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
30430 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
30440 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
30450 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
30460 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
30470 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
30480 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
30490 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
304a0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
304b0 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
304c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
304d0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
304e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
304f0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
30500 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30510 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
30520 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
30530 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
30540 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
30550 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
30560 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
30570 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
30580 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
30590 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
305a0 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
305b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
305c0 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
305d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
305e0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
305f0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
30600 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
30610 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
30620 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
30630 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
30640 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30650 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
30660 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
30670 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
30680 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
30690 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
306a0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
306b0 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
306c0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
306d0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
306e0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
306f0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
30700 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
30710 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
30720 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
30730 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
30740 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
30750 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
30760 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
30770 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
30780 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
30790 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
307a0 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
307b0 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
307c0 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
307d0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
307e0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
307f0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
30800 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
30810 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
30820 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
30830 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
30840 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
30850 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
30860 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
30870 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
30880 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
30890 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
308a0 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
308b0 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
308c0 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
308d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
308e0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
308f0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
30900 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
30910 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
30920 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
30930 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
30940 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
30950 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
30960 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
30970 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
30980 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
30990 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
309a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
309b0 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
309c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
309d0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
309e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
309f0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
30a00 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
30a10 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
30a20 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
30a30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30a40 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
30a50 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
30a60 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
30a70 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
30a80 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
30a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30aa0 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
30ab0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
30ac0 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
30ad0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
30ae0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
30af0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
30b00 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
30b10 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
30b20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30b30 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
30b40 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
30b50 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
30b60 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
30b70 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
30b80 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
30b90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30ba0 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
30bb0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
30bc0 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
30bd0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
30be0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30bf0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
30c00 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
30c10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30c20 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
30c30 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
30c40 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
30c50 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
30c60 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
30c70 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
30c80 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
30c90 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
30ca0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30cb0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
30cc0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
30cd0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
30ce0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
30cf0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
30d00 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
30d10 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
30d20 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
30d30 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
30d40 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
30d50 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
30d60 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
30d70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30d80 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
30d90 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
30da0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
30db0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
30dc0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
30dd0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
30de0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
30df0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
30e00 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
30e10 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
30e20 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
30e30 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
30e40 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
30e50 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
30e60 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
30e70 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
30e80 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
30e90 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
30ea0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
30eb0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
30ec0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
30ed0 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64  )^.*/.const void
30ee0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
30ef0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
30f00 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30f10 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30f20 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
30f30 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30f40 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30f50 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
30f60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30f70 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73   iCol);.double s
30f80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
30f90 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
30fa0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
30fb0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
30fc0 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  n_int(sqlite3_st
30fd0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30fe0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
30ff0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31000 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
31010 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e  , int iCol);.con
31020 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  st unsigned char
31030 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31040 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
31050 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31060 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31070 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
31080 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
31090 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
310a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
310b0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
310c0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71  *, int iCol);.sq
310d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
310e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
310f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31100 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
31110 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
31120 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
31130 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
31140 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
31150 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31160 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31170 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
31180 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
31190 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
311a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
311b0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
311c0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
311d0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
311e0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
311f0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
31200 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
31210 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
31220 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
31230 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31240 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
31250 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
31260 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
31270 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
31280 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
31290 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
312a0 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
312b0 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
312c0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
312d0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
312e0 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
312f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
31300 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
31310 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
31320 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
31330 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
31340 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
31350 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31360 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
31370 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
31380 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
31390 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
313a0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
313b0 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
313c0 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
313d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
313e0 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
313f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
31400 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
31410 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
31420 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
31430 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
31440 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
31450 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
31460 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
31470 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
31480 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
31490 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
314a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
314b0 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
314c0 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
314d0 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
314e0 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
314f0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
31500 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
31510 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
31520 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
31530 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
31540 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
31550 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
31560 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
31570 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
31580 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
31590 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
315a0 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
315b0 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
315c0 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
315d0 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
315e0 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  on..*/.int sqlit
315f0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
31600 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
31610 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31620 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
31630 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
31640 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
31650 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31660 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
31670 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
31680 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
31690 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
316a0 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
316b0 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
316c0 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
316d0 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
316e0 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
316f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
31700 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
31710 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
31720 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
31730 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
31740 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
31750 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
31760 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
31770 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
31780 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
31790 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
317a0 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
317b0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
317c0 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
317d0 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
317e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
317f0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
31800 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
31810 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
31820 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
31830 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
31840 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
31850 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
31860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31870 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
31880 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
31890 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
318a0 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
318b0 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
318c0 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
318d0 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
318e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
318f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
31900 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
31910 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31920 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
31930 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
31940 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
31950 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31960 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
31970 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
31980 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
31990 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
319a0 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
319b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
319c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
319d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
319e0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
319f0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
31a00 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
31a10 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
31a20 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
31a30 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
31a40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73  .int sqlite3_res
31a50 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
31a60 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31a70 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
31a80 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
31a90 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
31aa0 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
31ab0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
31ac0 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
31ad0 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31ae0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31af0 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
31b00 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31b10 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31b20 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
31b30 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
31b40 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
31b50 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
31b60 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
31b70 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
31b80 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
31b90 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
31ba0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
31bb0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
31bc0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
31bd0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
31be0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
31bf0 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
31c00 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
31c10 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
31c20 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
31c30 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
31c40 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
31c50 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
31c60 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
31c70 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
31c80 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
31c90 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
31ca0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
31cb0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
31cc0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
31cd0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
31ce0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
31cf0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
31d00 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
31d10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31d20 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
31d30 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
31d40 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
31d50 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
31d60 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
31d70 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
31d80 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
31d90 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
31da0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
31db0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
31dc0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
31dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31de0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
31df0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
31e00 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
31e10 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
31e20 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
31e30 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
31e40 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
31e50 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
31e60 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
31e70 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
31e80 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
31e90 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
31ea0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
31eb0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
31ec0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
31ed0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
31ee0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
31ef0 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
31f00 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
31f10 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
31f20 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
31f30 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
31f40 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
31f50 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
31f60 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
31f70 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
31f80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
31f90 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
31fa0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
31fb0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
31fc0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
31fd0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
31fe0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
31ff0 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
32000 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
32010 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
32020 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
32030 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
32040 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
32050 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
32060 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
32070 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
32080 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
32090 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
320a0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
320b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
320c0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
320d0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
320e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
320f0 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
32100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
32110 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
32120 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
32130 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
32140 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
32150 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
32160 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
32170 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
32180 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
32190 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
321a0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
321b0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
321c0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
321d0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
321e0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
321f0 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
32200 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
32210 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
32220 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
32230 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
32240 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
32250 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
32260 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
32270 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
32280 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
32290 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
322a0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
322b0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
322c0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
322d0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
322e0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
322f0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
32300 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
32310 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
32320 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32330 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
32340 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
32350 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
32360 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
32370 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
32380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32390 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
323a0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
323b0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
323c0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
323d0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
323e0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
323f0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
32400 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
32410 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
32420 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
32430 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
32440 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
32450 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
32460 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
32470 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
32480 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
32490 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
324a0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
324b0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
324c0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
324d0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
324e0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
324f0 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
32500 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
32510 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32520 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
32530 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
32540 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
32550 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
32560 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
32570 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
32580 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
32590 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
325a0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
325b0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
325c0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
325d0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
325e0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
325f0 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
32600 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
32610 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
32620 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
32630 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
32640 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32650 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
32660 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
32670 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
32680 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
32690 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
326a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
326b0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
326c0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
326d0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
326e0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
326f0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
32700 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
32710 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
32720 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
32730 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
32740 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
32750 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
32760 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
32770 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
32780 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
32790 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
327a0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
327b0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
327c0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
327d0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
327e0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
327f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
32800 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32810 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
32820 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
32830 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
32840 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
32850 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
32860 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
32870 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
32880 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
32890 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
328a0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
328b0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
328c0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
328d0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
328e0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
328f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
32900 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
32910 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
32920 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
32930 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
32940 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
32950 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
32960 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
32970 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
32980 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
32990 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
329a0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
329b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
329c0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
329d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
329e0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
329f0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
32a00 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32a10 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
32a20 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
32a30 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
32a40 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
32a50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
32a60 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
32a70 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
32a80 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
32a90 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
32aa0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32ab0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
32ac0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
32ad0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
32ae0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
32af0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
32b00 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
32b10 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
32b20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
32b30 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
32b40 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
32b50 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
32b60 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
32b70 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
32b80 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
32b90 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
32ba0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
32bb0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
32bc0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
32bd0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
32be0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
32bf0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
32c00 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
32c10 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
32c20 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
32c30 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
32c40 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
32c50 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
32c60 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
32c70 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
32c80 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
32c90 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32ca0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
32cb0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
32cc0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
32cd0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
32ce0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
32cf0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
32d00 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
32d10 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
32d20 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32d30 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32d40 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
32d50 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
32d60 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
32d70 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
32d80 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
32d90 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
32da0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
32db0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32dc0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
32dd0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
32de0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
32df0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
32e00 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
32e10 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
32e20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
32e30 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
32e40 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
32e50 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
32e60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
32e70 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
32e80 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
32e90 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
32ea0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
32eb0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
32ec0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
32ed0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
32ee0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
32ef0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
32f00 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
32f10 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
32f20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
32f30 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
32f40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32f50 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
32f60 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
32f70 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
32f80 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
32f90 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
32fa0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
32fb0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
32fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32fd0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
32fe0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
32ff0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33000 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33010 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33020 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
33030 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33040 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
33050 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33060 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
33070 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
33080 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
33090 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
330a0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
330b0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
330c0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
330d0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
330e0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
330f0 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33100 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33110 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33120 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33130 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
33140 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
33150 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33160 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
33170 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
33180 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
33190 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
331a0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
331b0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
331c0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
331d0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
331e0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
331f0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
33200 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
33210 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
33220 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
33230 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
33240 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33250 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
33260 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
33270 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33280 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
33290 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
332a0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
332b0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
332c0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
332d0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
332e0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
332f0 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
33300 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33310 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
33320 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
33330 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
33340 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
33350 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
33360 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
33370 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
33380 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
33390 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
333a0 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
333b0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
333c0 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
333d0 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
333e0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
333f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
33400 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
33410 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
33420 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
33430 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
33440 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
33450 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33460 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
33470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33480 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.**
33490 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
334a0 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20  nts may be ORed 
334b0 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68  together with th
334c0 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  e .** [SQLITE_UT
334d0 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74  F8 | preferred t
334e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73  ext encoding] as
334f0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
33500 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ment.** to [sqli
33510 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33520 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
33530 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
33540 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
33550 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33560 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  ction_v2()]..*/.
33570 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
33580 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20  ETERMINISTIC    
33590 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  0x800../*.** CAP
335a0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
335b0 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
335c0 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
335d0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
335e0 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
335f0 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
33600 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
33610 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
33620 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
33630 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
33640 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
33650 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
33660 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
33670 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
33680 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
33690 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
336a0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63  nctions.  To enc
336b0 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65  ourage programme
336c0 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74  rs to avoid.** t
336d0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
336e0 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c  we will not expl
336f0 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f  ain what they do
33700 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
33710 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41  ITE_OMIT_DEPRECA
33720 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  TED.SQLITE_DEPRE
33730 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33740 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
33750 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
33760 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
33770 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33780 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
33790 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
337a0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
337b0 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
337c0 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
337d0 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
337e0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
337f0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
33800 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
33810 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
33820 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33830 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72  void sqlite3_thr
33840 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64  ead_cleanup(void
33850 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
33860 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33870 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
33880 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
33890 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a  te3_int64,int),.
338a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
338b0 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69        void*,sqli
338c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64  te3_int64);.#end
338d0 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
338e0 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
338f0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
33900 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
33910 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61  e.**.** The C-la
33920 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74  nguage implement
33930 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e  ation of SQL fun
33940 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
33950 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68  gates uses.** th
33960 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66  is set of interf
33970 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ace routines to 
33980 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d  access the param
33990 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a  eter values on.*
339a0 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f  * the function o
339b0 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a  r aggregate.  .*
339c0 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
339d0 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
339e0 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
339f0 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
33a00 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
33a10 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33a20 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
33a30 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33a40 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
33a50 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
33a60 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
33a70 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
33a80 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
33a90 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
33aa0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
33ab0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
33ac0 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
33ad0 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
33ae0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
33af0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
33b00 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
33b10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33b20 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
33b30 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
33b40 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
33b50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
33b60 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
33b70 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
33b80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
33b90 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
33ba0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
33bb0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
33bc0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
33bd0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33be0 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
33bf0 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
33c00 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
33c10 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
33c20 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
33c30 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
33c40 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
33c50 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
33c60 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
33c70 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
33c80 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
33c90 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
33ca0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
33cb0 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e  hat these routin
33cc0 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
33cd0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
33ce0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
33cf0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
33d00 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
33d10 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
33d20 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
33d30 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
33d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33d50 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
33d60 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
33d70 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
33d80 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
33d90 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
33da0 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
33db0 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
33dc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33dd0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
33de0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
33df0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
33e00 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
33e10 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
33e20 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
33e30 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
33e40 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
33e50 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
33e60 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
33e70 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
33e80 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
33e90 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
33ea0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
33eb0 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
33ec0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
33ed0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
33ee0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
33ef0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
33f00 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
33f10 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
33f20 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
33f30 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
33f40 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
33f50 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
33f60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
33f70 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
33f80 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
33f90 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
33fa0 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
33fb0 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
33fc0 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
33fd0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
33fe0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
33ff0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
34000 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
34010 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
34020 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
34030 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
34040 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
34050 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
34060 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
34070 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34080 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
34090 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
340a0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
340b0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
340c0 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
340d0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
340e0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
340f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
34100 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
34110 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
34120 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
34130 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
34140 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34150 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
34160 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
34170 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34180 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34190 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
341a0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
341b0 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
341c0 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
341d0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73  ameters..*/.cons
341e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
341f0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
34200 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
34210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34220 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
34230 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
34240 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
34250 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34260 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76  double sqlite3_v
34270 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69  alue_double(sqli
34280 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
34290 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
342a0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
342b0 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  *);.sqlite3_int6
342c0 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  4 sqlite3_value_
342d0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61  int64(sqlite3_va
342e0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  lue*);.const uns
342f0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
34300 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73  te3_value_text(s
34310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34320 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34330 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34340 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34350 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
34360 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34370 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
34380 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
34390 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
343a0 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
343b0 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
343c0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
343d0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
343e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
343f0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
34400 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34420 46 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53  F: Finding The S
34430 75 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61  ubtype Of SQL Va
34440 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
34450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
34460 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
34470 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29  value_subtype(V)
34480 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
34490 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  s the subtype fo
344a0 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61  r.** an [applica
344b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
344c0 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d   function] argum
344d0 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74  ent V.  The subt
344e0 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ype.** informati
344f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
34500 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64  o pass a limited
34510 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
34520 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53  xt from.** one S
34530 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61  QL function to a
34540 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65  nother.  Use the
34550 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
34560 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72  _subtype()].** r
34570 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68  outine to set th
34580 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68  e subtype for th
34590 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
345a0 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  f an SQL functio
345b0 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
345c0 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20  makes no use of 
345d0 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20  subtype itself. 
345e0 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65   It merely passe
345f0 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a  s the subtype.**
34600 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74   from the result
34610 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61   of one [applica
34620 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
34630 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20   function] into 
34640 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20  the.** input of 
34650 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69  another..*/.unsi
34660 67 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33  gned int sqlite3
34670 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
34680 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34690 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
346a0 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
346b0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
346c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
346d0 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
346e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
346f0 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
34700 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
34710 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34720 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
34730 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34740 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
34750 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
34760 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
34770 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
34780 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34790 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
347a0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
347b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
347c0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
347d0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
347e0 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
347f0 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
34800 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
34810 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
34820 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
34830 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
34840 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
34850 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
34860 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
34870 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
34880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
34890 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
348a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
348b0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
348c0 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
348d0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
348e0 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ..*/.sqlite3_val
348f0 75 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ue *sqlite3_valu
34900 65 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69  e_dup(const sqli
34910 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69  te3_value*);.voi
34920 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
34930 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  free(sqlite3_val
34940 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34950 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
34960 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
34970 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48   Context.** METH
34980 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
34990 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
349a0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
349b0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
349c0 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
349d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
349e0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
349f0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
34a00 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
34a10 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
34a20 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34a30 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
34a40 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
34a50 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
34a60 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
34a70 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
34a80 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
34a90 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
34aa0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
34ab0 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
34ac0 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
34ad0 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
34ae0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
34af0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
34b00 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
34b10 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
34b20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
34b30 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
34b40 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
34b50 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
34b60 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
34b70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34b80 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
34b90 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
34ba0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
34bb0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
34bc0 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
34bd0 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
34be0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
34bf0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
34c00 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
34c10 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
34c20 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
34c30 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
34c40 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
34c50 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
34c60 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
34c70 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
34c80 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
34c90 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
34ca0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
34cb0 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
34cc0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34cd0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
34ce0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
34cf0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
34d00 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
34d10 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
34d20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
34d30 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34d40 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
34d50 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
34d60 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72  ter .** when fir
34d70 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69  st called if N i
34d80 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  s less than or e
34d90 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20  qual to zero or 
34da0 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  if a memory.** a
34db0 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63  llocate error oc
34dc0 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  curs..**.** ^(Th
34dd0 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63  e amount of spac
34de0 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73  e allocated by s
34df0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34e00 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73  _context(C,N) is
34e10 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62  .** determined b
34e20 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65  y the N paramete
34e30 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65  r on first succe
34e40 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61  ssful call.  Cha
34e50 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c  nging the.** val
34e60 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65  ue of N in subse
34e70 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
34e80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34e90 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e  context() within
34ea0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67  .** the same agg
34eb0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
34ec0 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f  instance will no
34ed0 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d  t resize the mem
34ee0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
34ef0 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65  n.)^  Within the
34f00 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
34f10 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72  , it is customar
34f20 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20  y to set.** N=0 
34f30 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  in calls to sqli
34f40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34f50 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68  ntext(C,N) so th
34f60 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c  at no .** pointl
34f70 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ess memory alloc
34f80 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a  ations occur..**
34f90 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
34fa0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
34fb0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
34fc0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
34fd0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34fe0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
34ff0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
35000 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
35010 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
35020 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
35030 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
35040 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
35050 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
35060 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
35070 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
35080 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
35090 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
350a0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
350b0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
350c0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
350d0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
350e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
350f0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
35100 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35110 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
35120 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
35130 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35140 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
35150 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35160 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
35170 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
35180 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
35190 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
351a0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
351b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
351c0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
351d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
351e0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
351f0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
35200 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
35210 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
35220 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
35230 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
35240 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
35250 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
35260 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
35270 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
35280 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35290 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
352a0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
352b0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
352c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
352d0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
352e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
352f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
35300 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
35310 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
35320 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35330 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35340 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35350 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73  void *sqlite3_us
35360 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f  er_data(sqlite3_
35370 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
35380 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
35390 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
353a0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
353b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
353c0 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
353d0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
353e0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
353f0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35400 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
35410 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
35420 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35430 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
35440 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
35450 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
35460 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35470 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
35480 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35490 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
354a0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
354b0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
354c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
354d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
354e0 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69  */.sqlite3 *sqli
354f0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
35500 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  andle(sqlite3_co
35510 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ntext*);../*.** 
35520 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69  CAPI3REF: Functi
35530 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74  on Auxiliary Dat
35540 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  a.** METHOD: sql
35550 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
35560 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
35570 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62  ns may be used b
35580 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65  y (non-aggregate
35590 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  ) SQL functions 
355a0 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20  to.** associate 
355b0 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72  metadata with ar
355c0 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49  gument values. I
355d0 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65  f the same value
355e0 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a   is passed to.**
355f0 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61   multiple invoca
35600 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
35610 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64  e SQL function d
35620 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63  uring query exec
35630 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20  ution, under.** 
35640 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63  some circumstanc
35650 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65  es the associate
35660 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62  d metadata may b
35670 65 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e  e preserved.  An
35680 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77   example.** of w
35690 68 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20  here this might 
356a0 62 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20  be useful is in 
356b0 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73  a regular-expres
356c0 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a  sion matching.**
356d0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
356e0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
356f0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
35700 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
35710 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65   stored as.** me
35720 74 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65  tadata associate
35730 64 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65  d with the patte
35740 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20  rn string.  .** 
35750 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20  Then as long as 
35760 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69  the pattern stri
35770 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73  ng remains the s
35780 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70  ame,.** the comp
35790 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70  iled regular exp
357a0 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72  ression can be r
357b0 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c  eused on multipl
357c0 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
357d0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
357e0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ction..**.** ^Th
357f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
35800 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
35810 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35820 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
35830 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
35840 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
35850 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
35860 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
35870 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
35880 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
35890 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
358a0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
358b0 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61  there is no meta
358c0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
358d0 65 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63  ed with the func
358e0 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74  tion argument, t
358f0 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  his sqlite3_get_
35900 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
35910 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  ace.** returns a
35920 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
35930 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35940 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
35950 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65  N,P,X) interface
35960 20 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61   saves P as meta
35970 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
35980 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
35990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
359a0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
359b0 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a  n.  ^Subsequent.
359c0 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
359d0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
359e0 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72  C,N) return P fr
359f0 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  om the most rece
35a00 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  nt.** sqlite3_se
35a10 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c  t_auxdata(C,N,P,
35a20 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d  X) call if the m
35a30 65 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c  etadata is still
35a40 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c   valid or.** NUL
35a50 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  L if the metadat
35a60 61 20 68 61 73 20 62 65 65 6e 20 64 69 73 63 61  a has been disca
35a70 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65 72 20  rded..** ^After 
35a80 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  each call to sql
35a90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35aa0 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72 65 20  (C,N,P,X) where 
35ab0 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  X is not NULL,.*
35ac0 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  * SQLite will in
35ad0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
35ae0 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58 20 77  tor function X w
35af0 69 74 68 20 70 61 72 61 6d 65 74 65 72 20 50 20  ith parameter P 
35b00 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63 65 2c  exactly.** once,
35b10 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61 64 61   when the metada
35b20 74 61 20 69 73 20 64 69 73 63 61 72 64 65 64 2e  ta is discarded.
35b30 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
35b40 65 65 20 74 6f 20 64 69 73 63 61 72 64 20 74 68  ee to discard th
35b50 65 20 6d 65 74 61 64 61 74 61 20 61 74 20 61 6e  e metadata at an
35b60 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64 69 6e  y time, includin
35b70 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  g: <ul>.** <li> 
35b80 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70  when the corresp
35b90 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  onding function 
35ba0 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67 65  parameter change
35bb0 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68  s, or.** <li> wh
35bc0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
35bd0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
35be0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
35bf0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
35c00 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61 74 65  *      SQL state
35c10 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ment, or.** <li>
35c20 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 65   when sqlite3_se
35c30 74 5f 61 75 78 64 61 74 61 28 29 20 69 73 20 69  t_auxdata() is i
35c40 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f 6e 20  nvoked again on 
35c50 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d 65 74  the same paramet
35c60 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 64  er, or.** <li> d
35c70 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67 69 6e  uring the origin
35c80 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  al sqlite3_set_a
35c90 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20 77 68  uxdata() call wh
35ca0 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a 2a 20  en a memory .** 
35cb0 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20       allocation 
35cc0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 3c 2f  error occurs. </
35cd0 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  ul>)^.**.** Note
35ce0 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c 65 74   the last bullet
35cf0 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72 2e 20   in particular. 
35d00 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
35d10 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74 65 33  X in .** sqlite3
35d20 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
35d30 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65 20 63  ,P,X) might be c
35d40 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  alled immediatel
35d50 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a 2a 2a  y, before the.**
35d60 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35d70 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
35d80 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e 20 20   even returns.  
35d90 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f 73 65  Hence sqlite3_se
35da0 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a 20 73  t_auxdata().** s
35db0 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65 64 20  hould be called 
35dc0 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f 66 20  near the end of 
35dd0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  the function imp
35de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20  lementation and 
35df0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
35e00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
35e10 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65 20 61  hould not make a
35e20 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66 74 65  ny use of P afte
35e30 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  r.** sqlite3_set
35e40 5f 61 75 78 64 61 74 61 28 29 20 68 61 73 20 62  _auxdata() has b
35e50 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a 0a 2a  een called..**.*
35e60 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c  * ^(In practice,
35e70 20 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65   metadata is pre
35e80 73 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66  served between f
35e90 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f  unction calls fo
35ea0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  r.** function pa
35eb0 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61 72  rameters that ar
35ec0 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63  e compile-time c
35ed0 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c 75 64  onstants, includ
35ee0 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76  ing literal.** v
35ef0 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61 6d  alues and [param
35f00 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70 72 65  eters] and expre
35f10 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65 64 20  ssions composed 
35f20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e 29 5e  from the same.)^
35f30 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35f40 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
35f50 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35f60 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35f70 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
35f80 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35f90 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
35fa0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35fb0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35fc0 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64 20 73  , int N);.void s
35fd0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35fe0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35ff0 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
36000 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
36010 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
36020 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
36030 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
36040 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
36050 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
36060 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
36070 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
36080 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
36090 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
360a0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
360b0 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
360c0 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
360d0 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
360e0 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
360f0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
36100 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
36110 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
36120 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
36130 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
36140 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
36150 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
36160 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
36170 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
36180 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
36190 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
361a0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
361b0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
361c0 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
361d0 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
361e0 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
361f0 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
36200 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
36210 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
36220 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
36230 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
36240 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
36250 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
36260 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
36270 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
36280 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
36290 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
362a0 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
362b0 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
362c0 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
362d0 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
362e0 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
362f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
36300 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
36310 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
36320 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
36330 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
36340 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
36350 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
36360 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
36370 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 54  _context.**.** T
36380 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
36390 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
363a0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
363b0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
363c0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
363d0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
363e0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
363f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36400 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36410 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36420 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
36430 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
36440 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
36450 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
36460 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
36470 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
36480 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
36490 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
364a0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
364b0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
364c0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
364d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
364e0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
364f0 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
36500 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
36510 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
36520 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
36530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36540 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
36550 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36560 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
36570 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
36580 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36590 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
365a0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
365b0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
365c0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
365d0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
365e0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
365f0 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
36600 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
36610 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
36620 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
36630 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61 6e 64  eroblob(C,N) and
36640 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36650 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e 29 0a  zeroblob64(C,N).
36660 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  ** interfaces se
36670 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  t the result of 
36680 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36690 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
366a0 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c 4f 42   to be.** a BLOB
366b0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
366c0 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64 20 4e  zero bytes and N
366d0 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2e 0a   bytes in size..
366e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
366f0 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
36700 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36710 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
36720 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
36730 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36740 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
36750 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
36760 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
36770 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
36780 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
367a0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
367b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
367c0 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
367d0 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
367e0 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
367f0 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
36800 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
36810 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
36820 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
36830 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
36840 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
36850 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36860 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
36870 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
36880 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
36890 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
368a0 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
368b0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
368c0 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
368d0 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
368e0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
368f0 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
36900 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
36910 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
36920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36930 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
36940 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
36950 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
36960 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
36970 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
36980 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
36990 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
369a0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
369b0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
369c0 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
369d0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
369e0 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
369f0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
36a00 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
36a10 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
36a20 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
36a30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36a40 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
36a50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36a60 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
36a70 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
36a80 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
36a90 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
36aa0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
36ab0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
36ac0 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
36ad0 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
36ae0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36af0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
36b00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36b10 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
36b20 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
36b30 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
36b40 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
36b50 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
36b60 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
36b70 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
36b80 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
36b90 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
36ba0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
36bb0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
36bc0 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
36bd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36be0 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
36bf0 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
36c00 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
36c10 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
36c20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
36c30 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
36c40 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
36c50 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
36c60 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
36c70 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
36c80 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
36c90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36ca0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
36cb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36cc0 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
36cd0 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
36ce0 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
36cf0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36d00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
36d10 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  ig() interface c
36d20 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
36d30 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
36d40 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
36d50 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  t a string or BL
36d60 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74  OB is too long t
36d70 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a  o represent..**.
36d80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36d90 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d  result_error_nom
36da0 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  em() interface c
36db0 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20  auses SQLite to 
36dc0 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f  throw an.** erro
36dd0 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61  r indicating tha
36de0 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  t a memory alloc
36df0 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a  ation failed..**
36e00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36e10 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e  _result_int() in
36e20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
36e30 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
36e40 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
36e50 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36e60 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33  tion to be the 3
36e70 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  2-bit signed int
36e80 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
36e90 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
36ea0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
36eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36ec0 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  int64() interfac
36ed0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
36ee0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
36ef0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36f00 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36f10 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74 20  o be the 64-bit 
36f20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
36f30 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
36f40 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
36f50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
36f60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c  lite3_result_nul
36f70 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  l() interface se
36f80 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
36f90 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
36fa0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36fb0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
36fc0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
36fd0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36fe0 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33  _text(), sqlite3
36ff0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29  _result_text16()
37000 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  ,.** sqlite3_res
37010 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20  ult_text16le(), 
37020 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
37030 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e  lt_text16be() in
37040 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20  terfaces.** set 
37050 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37060 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37070 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37080 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
37090 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69 63  text string whic
370a0 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  h is represented
370b0 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31   as UTF-8, UTF-1
370c0 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  6 native byte or
370d0 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c  der,.** UTF-16 l
370e0 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72  ittle endian, or
370f0 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69   UTF-16 big endi
37100 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79  an, respectively
37110 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37120 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34 28  3_result_text64(
37130 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
37140 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
37150 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70 6c 69  e of an.** appli
37160 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37170 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37180 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e 20 61  text string in a
37190 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 73 70  n encoding.** sp
371a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
371b0 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74 29 20  ifth (and last) 
371c0 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68  parameter, which
371d0 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a 2a 20   must be one.** 
371e0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
371f0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  , [SQLITE_UTF16]
37200 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
37210 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  E], or [SQLITE_U
37220 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53 51 4c  TF16LE]..** ^SQL
37230 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
37240 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
37250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
37260 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
37270 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
37280 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37290 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
372a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
372b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
372c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
372d0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
372e0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
372f0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37300 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
37310 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
37320 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
37330 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
37340 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
37350 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37360 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37370 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37380 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
37390 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
373a0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
373b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
373c0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
373d0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
373e0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
373f0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
37400 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37410 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
37420 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
37430 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37440 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37450 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
37460 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
37470 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
37480 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
37490 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
374a0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
374b0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
374c0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
374d0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
374e0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
374f0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
37500 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
37510 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
37520 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
37530 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
37540 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
37550 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
37560 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
37570 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
37580 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
37590 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
375a0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
375b0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
375c0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
375d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
375e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
375f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37600 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37610 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
37620 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
37630 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
37640 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
37650 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
37660 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
37670 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
37680 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
37690 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
376a0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
376b0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
376c0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
376d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
376e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
376f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
37700 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
37710 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
37720 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
37730 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
37740 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
37750 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
37760 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
37770 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
37780 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
37790 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
377a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
377b0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
377c0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
377d0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
377e0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
377f0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
37800 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
37810 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
37820 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
37830 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37840 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
37850 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
37860 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
37870 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
37880 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
37890 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
378a0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
378b0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
378c0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
378d0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
378e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
378f0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
37900 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37910 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37920 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37930 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
37940 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
37950 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37960 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
37970 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72   of the.** [unpr
37980 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37990 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
379a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
379b0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
379c0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
379d0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
379e0 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
379f0 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
37a00 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
37a10 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
37a20 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
37a30 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
37a40 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
37a50 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
37a60 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
37a70 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37a80 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
37a90 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
37aa0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37ab0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37ac0 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
37ad0 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
37ae0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
37af0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37b00 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
37b10 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
37b20 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
37b30 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
37b40 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
37b50 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
37b60 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
37b70 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
37b80 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
37b90 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
37ba0 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
37bb0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
37bc0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37bd0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
37be0 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
37bf0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
37c00 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
37c10 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
37c20 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  fined..*/.void s
37c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
37c40 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
37c50 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37c60 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
37c70 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37c80 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
37c90 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
37ca0 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  xt*,const void*,
37cb0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37cc0 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
37cd0 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28  te3_uint64,void(
37ce0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37cf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37d00 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
37d10 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
37d20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37d30 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
37d40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
37d50 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
37d60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
37d70 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
37d80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
37d90 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
37da0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37db0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
37dc0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
37dd0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
37de0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37df0 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
37e00 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
37e10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37e20 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
37e30 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
37e40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37e50 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
37e60 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
37e70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37e80 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
37e90 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
37ea0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
37eb0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37ec0 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
37ed0 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
37ee0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37ef0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37f00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
37f10 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
37f20 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37f30 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36 34  e3_result_text64
37f40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37f50 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  *, const char*,s
37f60 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
37f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37f80 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
37f90 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
37fa0 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
37fb0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
37fc0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
37fd0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37fe0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37ff0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
38000 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
38010 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
38020 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38030 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
38040 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  nt,void(*)(void*
38050 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
38060 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
38070 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38080 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
38090 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
380a0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
380b0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73  3_result_value(s
380c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
380d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
380e0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
380f0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73  esult_zeroblob(s
38100 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
38110 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c   int n);.int sql
38120 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
38130 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
38140 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
38150 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a 2f 2a  _uint64 n);.../*
38160 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
38170 74 74 69 6e 67 20 54 68 65 20 53 75 62 74 79 70  tting The Subtyp
38180 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  e Of An SQL Func
38190 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  tion.** METHOD: 
381a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a  sqlite3_context.
381b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
381c0 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
381d0 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e 20 63  (C,T) function c
381e0 61 75 73 65 73 20 74 68 65 20 73 75 62 74 79 70  auses the subtyp
381f0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65 73 75  e of.** the resu
38200 6c 74 20 66 72 6f 6d 20 74 68 65 20 5b 61 70 70  lt from the [app
38210 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
38220 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 77   SQL function] w
38230 69 74 68 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ith .** [sqlite3
38240 5f 63 6f 6e 74 65 78 74 5d 20 43 20 74 6f 20 62  _context] C to b
38250 65 20 74 68 65 20 76 61 6c 75 65 20 54 2e 20 20  e the value T.  
38260 4f 6e 6c 79 20 74 68 65 20 6c 6f 77 65 72 20 38  Only the lower 8
38270 20 62 69 74 73 20 0a 2a 2a 20 6f 66 20 74 68 65   bits .** of the
38280 20 73 75 62 74 79 70 65 20 54 20 61 72 65 20 70   subtype T are p
38290 72 65 73 65 72 76 65 64 20 69 6e 20 63 75 72 72  reserved in curr
382a0 65 6e 74 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ent versions of 
382b0 53 51 4c 69 74 65 3b 0a 2a 2a 20 68 69 67 68 65  SQLite;.** highe
382c0 72 20 6f 72 64 65 72 20 62 69 74 73 20 61 72 65  r order bits are
382d0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 54   discarded..** T
382e0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 75 62  he number of sub
382f0 74 79 70 65 20 62 79 74 65 73 20 70 72 65 73 65  type bytes prese
38300 72 76 65 64 20 62 79 20 53 51 4c 69 74 65 20 6d  rved by SQLite m
38310 69 67 68 74 20 69 6e 63 72 65 61 73 65 0a 2a 2a  ight increase.**
38320 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
38330 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
38340 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  /.void sqlite3_r
38350 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 73 71  esult_subtype(sq
38360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 75  lite3_context*,u
38370 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b 0a 0a 2f  nsigned int);../
38380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38390 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74  efine New Collat
383a0 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a  ing Sequences.**
383b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
383c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
383d0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
383e0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
383f0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
38400 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
38410 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38420 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
38430 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
38440 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
38450 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
38460 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
38470 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
38480 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
38490 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
384a0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
384b0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
384c0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
384d0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
384e0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
384f0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
38500 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
38510 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
38520 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
38530 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
38540 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
38550 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
38560 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
38570 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
38580 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
38590 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
385a0 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
385b0 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
385c0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
385d0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
385e0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
385f0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
38600 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
38610 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
38620 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
38630 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
38640 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38650 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
38660 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
38670 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
38680 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
38690 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
386a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
386b0 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
386c0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
386d0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
386e0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
386f0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
38700 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
38710 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
38720 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
38730 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
38740 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
38750 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
38760 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
38770 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
38780 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
38790 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
387a0 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
387b0 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
387c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
387d0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
387e0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
387f0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
38800 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
38810 73 20 74 68 65 20 66 69 72 73 74 20