System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 07d37c1cf87f53f7a1ead4d4513233f97ed7e26b:


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 33 2e 31 30 2e 30 22 0a 23 64       "3.10.0".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 30  SION_NUMBER 3010
10d0: 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  000.#define SQLI
10e0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20 20 20  TE_SOURCE_ID    
10f0: 20 20 22 32 30 31 35 2d 31 32 2d 30 34 20 31 33    "2015-12-04 13
1100: 3a 34 34 3a 30 37 20 34 65 63 62 63 37 35 62 34  :44:07 4ecbc75b4
1110: 36 35 35 33 33 63 66 38 30 65 31 36 36 61 39 64  65533cf80e166a9d
1120: 30 38 37 39 62 39 61 66 64 33 66 65 32 62 65 22  0879b9afd3fe2be"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65  ader, and thus e
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  r of.** of sqlit
3ac0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3ad0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3ae0: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3af0: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b00: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b10: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b20: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b30: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b40: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b50: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b60: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b70: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3b80: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3b90: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3ba0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3bc0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bd0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3be0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3bf0: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c00: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c10: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c20: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c30: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c40: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c50: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c60: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c70: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3c80: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3c90: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3ca0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cb0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3cc0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cd0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3ce0: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3cf0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d00: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d10: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d20: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d30: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d40: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d50: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d60: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d70: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3d80: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3d90: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3da0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3db0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3dc0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3dd0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3de0: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3df0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e00: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e20: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e30: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e40: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e50: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e60: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e70: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3e80: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3e90: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ea0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3eb0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ec0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ed0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3ee0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ef0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f00: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f10: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f20: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f30: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f40: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f50: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f60: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f70: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3f80: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3f90: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fa0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fb0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fc0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3fd0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
3fe0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
3ff0: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4000: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4010: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4020: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4030: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4040: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4050: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4060: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4070: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
4080: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4090: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40a0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40c0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
40e0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
40f0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4100: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4110: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4120: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4130: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4140: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4150: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4160: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4170: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
4180: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
4190: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
41a0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
41b0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
41c0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
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 2f 2a 20 41 6e 20 6f           /* An o
41f0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4200: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4210: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4230: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4240: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4250: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4260: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4270: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
4280: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
4290: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
42c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
42d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
42e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4310: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4320: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4330: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4340: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4350: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
4360: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4370: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4380: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4390: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
43a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
43b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
43c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
43d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
43e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
43f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
4400: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4410: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4420: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4430: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
4440: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4450: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
4460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4470: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4480: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
4490: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
44a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
44b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
44c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
44d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
44e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
44f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4500: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4510: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4520: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4530: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4540: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4550: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4560: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4570: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
4590: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
45a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
45b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
45c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
45d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
45e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
45f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4600: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4610: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4620: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4630: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4640: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4650: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4660: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4670: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4680: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
4690: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
46a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
46b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
46c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
46d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
46f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4700: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4710: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4720: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4730: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4740: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4750: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4760: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4780: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
4790: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
47a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
47b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
47c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
47d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
47e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
47f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
4800: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
4810: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4820: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4830: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4840: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4850: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4860: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4870: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4880: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4890: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
48a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
48c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
48d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
48e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
48f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4900: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4910: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
4920: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
4930: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
4940: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
4950: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
4960: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
4970: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4980: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4990: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
49a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
49b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
49c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
49d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
49e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
49f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4a00: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4a10: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
4a20: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
4a30: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
4a40: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
4a50: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
4a60: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
4a70: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4a80: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4a90: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
4aa0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
4ab0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4ac0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
4ad0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
4ae0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
4af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4b00: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4b10: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4b20: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4b30: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4b40: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4b50: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4b60: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4b70: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4b80: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4b90: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
4ba0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
4bb0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
4bc0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
4bd0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4be0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
4bf0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
4c00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
4c10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4c20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
4c30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
4c40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
4c50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4c60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4c70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4c80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4c90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4ca0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4cb0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4cc0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4cd0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ce0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4cf0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4d00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4d10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4d20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4d30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4d40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4d50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4d60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
4d70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4d80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4d90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4da0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
4db0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
4dc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4dd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4de0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4df0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4e00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4e10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4e20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4e30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4e40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4e50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4e60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4e70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4e80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4e90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4ea0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4eb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4ec0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4ed0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ee0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4ef0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4f00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4f10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4f20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4f30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e  rs. These [exten
4f40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4f50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  ] are enabled or
4f60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4f70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4f80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4f90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4fa0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4fb0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4fc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74  PI.  Or, the ext
4fd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a  ended code for.*
4fe0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
4ff0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f  t error can be o
5000: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  btained using.**
5010: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
5020: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a  ed_errcode()]..*
5030: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5040: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
5050: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5060: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
5070: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5080: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
5090: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50a0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
50b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
50c0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
50d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
50e0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
50f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5100: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
5110: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5120: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
5130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5140: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
5150: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5160: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
5170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5180: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
5190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51a0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
51f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5200: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5210: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5220: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5230: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5240: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5250: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5260: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5280: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
52c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5300: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5320: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5340: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5360: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5380: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
53c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5400: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5420: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5440: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5480: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
54c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
54d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
54f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5500: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5510: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5520: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5540: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5550: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5560: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5570: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5580: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5590: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
55b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
55c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
55d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
55e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
55f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5600: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5610: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5620: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5630: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5640: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5650: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5660: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5670: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5680: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5690: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
56a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
56b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e   SQLITE_IOERR_VN
56c0: 4f 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ODE             
56d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
56e0: 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (27<<8)).#define
56f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55   SQLITE_IOERR_AU
5700: 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
5710: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5720: 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (28<<8)).#define
5730: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
5740: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5750: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5760: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5770: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5780: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5790: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
57a0: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
57b0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
57c0: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
57d0: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
57e0: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
57f0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5800: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5810: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
5820: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
5830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5840: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
5850: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5860: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
5870: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5880: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5890: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
58a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
58b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58c0: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
58d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
58e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
58f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5900: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5910: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5920: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5930: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5940: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5950: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5960: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5970: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5980: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5990: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
59a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
59b0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
59c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
59d0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
59e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
59f0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5a00: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5a10: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
5a20: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5a30: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
5a40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5a50: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5a60: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5a70: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5a80: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a90: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5aa0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5ab0: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5ac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ad0: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5ae0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5af0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5b00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b10: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5b20: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5b30: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b40: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5b50: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b60: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5b70: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b80: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5b90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5ba0: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5bb0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5bc0: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5be0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5bf0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5c00: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5c10: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5c20: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5c30: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5c40: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c50: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5c60: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c70: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5c80: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c90: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5ca0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5cb0: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5cc0: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5cd0: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cf0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5d00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5d10: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5d20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d30: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d40: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5d50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5d60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d70: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d80: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5d90: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5da0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5db0: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5dc0: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5dd0: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5de0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5df0: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20  ITE_AUTH_USER   
5e00: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5e10: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38  ITE_AUTH | (1<<8
5e20: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5e30: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5e40: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5e50: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5e60: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5e70: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5e80: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5e90: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5ea0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5eb0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5ec0: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5ed0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5ee0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5ef0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5f00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f10: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5f20: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5f30: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f40: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f60: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5f70: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5f80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5fa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fb0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5fc0: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5fd0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5fe0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6000: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
6010: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
6020: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6040: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
6050: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
6060: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6080: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6090: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
60a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
60b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60c0: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
60d0: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
60e0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60f0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6100: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6110: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
6120: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
6130: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6140: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6160: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
6170: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6180: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6190: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61a0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
61b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
61c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
61d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
61e0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
61f0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
6200: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6210: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6220: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
6230: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
6240: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6250: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6260: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
6270: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
6280: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6290: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62a0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
62b0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
62c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
62d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
62e0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
62f0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
6300: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6320: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
6330: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
6340: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6350: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6370: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6380: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6390: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63a0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
63b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63c0: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
63d0: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
63e0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63f0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6410: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
6420: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
6430: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6440: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6460: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6470: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6480: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6490: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64b0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
64c0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
64d0: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
64e0: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
64f0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
6500: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
6510: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
6520: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
6530: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6540: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6550: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6560: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6570: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6580: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6590: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
65a0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
65b0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
65c0: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
65d0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
65e0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
65f0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
6600: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
6610: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6620: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
6630: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6640: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6650: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6660: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6670: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6680: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6690: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
66a0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
66b0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
66c0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
66d0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
66e0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
66f0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6700: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
6710: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
6720: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
6730: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6740: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6750: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6760: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6770: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6780: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6790: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
67a0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
67b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
67c0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
67d0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
67e0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
67f0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
6800: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
6810: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
6820: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
6830: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6840: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6850: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6860: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6870: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6880: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6890: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
68a0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
68b0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
68c0: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
68d0: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
68e0: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
68f0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
6900: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
6910: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
6920: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
6930: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6940: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6950: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6960: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6970: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6980: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6990: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
69a0: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
69b0: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
69c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
69d0: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
69e0: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
69f0: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
6a00: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
6a10: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
6a20: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
6a30: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6a40: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6a50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6a60: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a80: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6a90: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6aa0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6ab0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6ad0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6ae0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6af0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6b00: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6b10: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6b20: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6b30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b40: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6b50: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b60: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6b70: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b80: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6b90: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6ba0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6bb0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6bc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6bd0: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6be0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6bf0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6c00: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6c10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6c20: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6c30: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6c40: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c50: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6c60: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6c70: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6c80: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6c90: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6ca0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6cb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6cc0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6cd0: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6ce0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6cf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6d00: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6d10: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6d30: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6d40: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d50: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6d60: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6d70: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6d80: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6d90: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6da0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6db0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6dc0: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6dd0: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6de0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6df0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6e00: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6e10: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6e20: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e30: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6e40: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6e50: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6e60: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6e70: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6e80: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6e90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6ea0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6eb0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6ec0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6ed0: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6ee0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6ef0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6f00: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6f10: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6f20: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6f30: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6f40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6f50: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6f60: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6f70: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6f80: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6f90: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6fa0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6fb0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6fc0: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6fd0: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6fe0: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6ff0: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
7000: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
7010: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
7020: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
7030: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
7040: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
7050: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
7060: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
7070: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7080: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
7090: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
70a0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
70b0: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
70c0: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
70d0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70e0: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
70f0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
7100: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
7110: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
7120: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
7130: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
7140: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7150: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7160: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
7170: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
7180: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
7190: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
71a0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
71b0: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
71c0: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
71d0: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
71e0: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
71f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
7200: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
7210: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
7220: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
7230: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
7240: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
7250: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7260: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
7270: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
7280: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
7290: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
72a0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
72b0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
72c0: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
72d0: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
72e0: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
72f0: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
7300: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
7310: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
7320: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
7330: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
7340: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
7350: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
7360: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7370: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
7380: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
7390: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
73a0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
73b0: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
73c0: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
73d0: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
73e0: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7400: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
7410: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
7420: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
7430: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
7440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7450: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
7460: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
7470: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7480: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
7490: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
74a0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
74b0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
74c0: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
74d0: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
74e0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
74f0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
7500: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
7510: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
7520: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
7530: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
7540: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
7550: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
7560: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
7570: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
7580: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
7590: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
75a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
75b0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
75c0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
75d0: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
75e0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
75f0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
7600: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
7610: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
7620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
7630: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
7640: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7650: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
7660: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7670: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
7680: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
7690: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
76a0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
76b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
76c0: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
76d0: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
76e0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
76f0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
7700: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7710: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
7720: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
7730: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7740: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
7750: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
7760: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
7770: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
7780: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
7790: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
77a0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
77b0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
77c0: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
77d0: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
77e0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
77f0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
7800: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
7810: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
7820: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7830: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7840: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7850: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7860: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
7870: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7880: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7890: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
78a0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
78b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
78c0: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
78d0: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
78e0: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
78f0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
7900: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
7910: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
7920: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
7930: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7940: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
7950: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
7960: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7970: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7980: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7990: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
79a0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
79b0: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
79c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
79d0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
79e0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
79f0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
7a00: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
7a10: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
7a20: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
7a30: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7a40: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7a50: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7a60: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7a70: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7a80: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7a90: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7aa0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7ab0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7ac0: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7ad0: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7ae0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7af0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7b00: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7b10: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7b20: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7b30: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7b40: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7b50: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7b60: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7b70: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7b80: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b90: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7ba0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7bb0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7bc0: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7be0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7bf0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7c00: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7c10: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7c20: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7c30: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7c40: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7c50: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7c60: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7c70: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7c80: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7c90: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7ca0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7cb0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7cc0: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7cd0: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7ce0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7cf0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7d00: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7d10: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7d20: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7d30: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7d40: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7d50: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7d60: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7d70: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7d80: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7d90: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7da0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7db0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7dc0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7dd0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7de0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7df0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7e00: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7e10: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7e20: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7e30: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7e40: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7e50: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7e60: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7e70: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7e80: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7e90: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7ea0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7eb0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7ec0: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7ed0: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7ee0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7ef0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7f00: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7f10: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7f20: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7f30: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7f40: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7f50: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7f60: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7f70: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7f80: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7f90: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7fa0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7fb0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7fc0: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7fd0: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7fe0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7ff0: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
8000: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
8010: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
8020: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
8030: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
8040: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
8050: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
8060: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
8070: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
8080: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
8090: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
80a0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
80b0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
80c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
80d0: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
80e0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
80f0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
8100: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
8110: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
8120: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
8130: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
8140: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
8150: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
8160: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
8170: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
8180: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
8190: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
81a0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
81b0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
81c0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
81d0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
81e0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
81f0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8200: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8210: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8220: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8230: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
8240: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
8250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8260: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
8270: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8280: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
8290: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
82b0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82c0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
82d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
82e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
82f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8300: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8310: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8330: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8340: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
8350: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8360: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
8370: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8380: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8390: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
83a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
83b0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
83c0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
83d0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
83e0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
83f0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8400: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8410: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8420: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8430: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8440: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8450: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8460: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8470: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8480: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8490: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
84a0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
84b0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
84c0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
84d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
84e0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
84f0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8500: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8510: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8520: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8530: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8540: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8550: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8560: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8570: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8580: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8590: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
85a0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
85b0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
85c0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
85d0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
85e0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
85f0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8600: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8610: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8620: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8630: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8640: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8650: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8660: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8670: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8680: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8690: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
86a0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
86b0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
86c0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
86d0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
86e0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
86f0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8700: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8710: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8720: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8730: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8740: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8750: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8760: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8770: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8780: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8790: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
87a0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
87b0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
87c0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
87d0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
87e0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
87f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8800: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8810: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8820: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8830: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8840: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8850: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8860: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8880: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8890: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
88a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
88b0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
88c0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
88d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
88e0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
88f0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8900: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8910: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8920: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8930: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8940: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8950: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8960: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8970: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8980: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8990: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
89a0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
89b0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
89c0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
89d0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
89e0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
89f0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8a00: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8a10: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8a20: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8a30: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8a40: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8a50: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8a60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a70: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8a80: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8a90: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8aa0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8ab0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8ac0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8ad0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8ae0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8af0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8b00: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8b10: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8b20: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8b30: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8b40: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8b50: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8b60: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
8b70: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b80: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b90: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
8ba0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8bb0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8bc0: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8bd0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8be0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8bf0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8c00: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8c10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8c20: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8c30: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
8c40: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
8c50: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
8c60: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
8c70: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
8c80: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c90: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8ca0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8cb0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8cc0: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8cd0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8ce0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8cf0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8d00: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8d10: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
8d20: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8d30: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d40: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d50: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8d60: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d70: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8d80: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8d90: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8da0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8db0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8dc0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8dd0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8de0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8df0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8e00: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8e10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8e20: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8e30: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8e40: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8e50: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8e60: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8e70: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8e80: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8e90: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8ea0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8eb0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
8ec0: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
8ed0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
8ee0: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
8ef0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
8f00: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
8f10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8f20: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
8f30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8f40: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
8f50: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
8f60: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
8f70: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
8f80: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
8f90: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8fa0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
8fb0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
8fc0: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
8fd0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
8fe0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
8ff0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
9000: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
9010: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
9020: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
9030: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9040: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9050: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9060: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9070: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9080: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9090: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
90a0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
90b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
90c0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
90d0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
90e0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
90f0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
9100: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
9110: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
9120: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
9130: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9140: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9150: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9160: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9170: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9180: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9190: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
91a0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
91b0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
91c0: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
91d0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
91e0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
91f0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
9200: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
9210: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
9220: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
9230: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9240: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9250: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9260: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9270: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9280: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9290: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
92a0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
92b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
92c0: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
92d0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
92e0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
92f0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
9300: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9310: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9320: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9330: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9340: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9350: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9360: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9370: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
9380: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9390: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
93a0: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
93b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
93c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
93d0: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
93e0: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
93f0: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
9400: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9410: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
9420: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9430: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9440: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9450: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9460: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9470: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9480: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9490: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
94a0: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
94b0: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
94c0: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
94d0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
94e0: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
94f0: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
9500: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
9510: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
9520: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
9530: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9540: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9550: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9560: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9570: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9580: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9590: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
95a0: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
95b0: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
95c0: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
95d0: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
95e0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
95f0: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
9600: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
9610: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
9620: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
9630: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9640: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9650: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9660: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9670: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9680: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9690: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
96a0: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
96b0: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
96c0: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
96d0: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
96e0: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
96f0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
9700: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9710: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
9720: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
9730: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
9740: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9750: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9760: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
9770: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9780: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9790: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
97a0: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
97b0: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
97c0: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
97d0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
97e0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
97f0: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
9800: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
9810: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
9820: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
9830: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
9840: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
9850: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
9860: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
9870: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9880: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9890: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
98a0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
98b0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
98c0: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
98d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
98e0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
98f0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9900: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
9910: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
9920: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9930: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9940: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9950: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9970: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9980: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9990: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
99a0: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
99b0: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
99c0: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
99d0: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
99e0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
99f0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
9a00: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
9a10: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
9a20: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
9a30: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
9a40: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
9a50: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
9a60: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
9a70: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
9a80: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
9a90: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
9aa0: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
9ab0: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
9ac0: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
9ad0: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
9ae0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
9af0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
9b00: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
9b10: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
9b20: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
9b30: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
9b40: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
9b50: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
9b60: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
9b70: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
9b80: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
9b90: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
9ba0: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
9bb0: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
9bc0: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
9bd0: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
9be0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
9bf0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
9c00: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
9c10: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
9c20: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
9c30: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9c40: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
9c50: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
9c60: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
9c70: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
9c80: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9c90: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9ca0: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9cb0: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9cc0: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9cd0: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9ce0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9cf0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9d00: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9d10: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9d20: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9d30: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9d40: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9d50: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9d60: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9d70: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9d80: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9d90: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9da0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9db0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9dc0: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9dd0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9de0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9df0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9e00: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
9e10: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
9e20: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
9e30: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
9e40: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9e50: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
9e60: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
9e70: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9e80: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
9e90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
9ea0: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
9eb0: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
9ec0: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
9ed0: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
9ee0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9ef0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
9f00: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9f10: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
9f20: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
9f30: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
9f40: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
9f50: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
9f60: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
9f70: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
9f80: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
9f90: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
9fa0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
9fb0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
9fc0: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
9fd0: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
9fe0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
9ff0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
a000: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
a010: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
a020: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
a030: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a040: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a050: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a060: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a070: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a080: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a090: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a0a0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a0b0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a0c0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a0d0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a0e0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a0f0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a100: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a110: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a120: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a130: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a140: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a150: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a160: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a170: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a180: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a190: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a1a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a1b0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a1c0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a1d0: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a1e0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a1f0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a200: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a210: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a220: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a230: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a250: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a260: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a270: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a280: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a290: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a2a0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a2b0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a2c0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a2d0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a2e0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2f0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a300: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a310: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a320: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a330: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a340: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a350: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a360: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a370: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a380: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a390: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a3a0: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a3b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a3c0: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a3d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a3e0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a3f0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a400: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a410: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a420: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a430: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a440: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a450: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a460: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a470: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a480: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a490: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a4a0: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a4b0: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a4c0: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a4d0: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a4e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a4f0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a500: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a510: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a520: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a530: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a540: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a550: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a560: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a570: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a580: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a590: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a5a0: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a5b0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a5c0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a5d0: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a5e0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a5f0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a600: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a610: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a620: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a630: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a640: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a650: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a660: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a670: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a680: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a690: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a6a0: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a6b0: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a6c0: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a6d0: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a6e0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a6f0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a700: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a710: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a720: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a730: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a740: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a750: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a760: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a770: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a780: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a790: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a7a0: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a7b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a7c0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
a7d0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
a7e0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
a7f0: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 66 69 6e  NTER] opcode fin
a800: 64 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ds a pointer to 
a810: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a  the top-level.**
a820: 20 5b 56 46 53 65 73 5d 20 63 75 72 72 65 6e 74   [VFSes] current
a830: 6c 79 20 69 6e 20 75 73 65 2e 20 20 5e 28 54 68  ly in use.  ^(Th
a840: 65 20 61 72 67 75 6d 65 6e 74 20 58 20 69 6e 0a  e argument X in.
a850: 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  ** sqlite3_file_
a860: 63 6f 6e 74 72 6f 6c 28 64 62 2c 53 51 4c 49 54  control(db,SQLIT
a870: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
a880: 54 45 52 2c 58 29 20 6d 75 73 74 20 62 65 0a 2a  TER,X) must be.*
a890: 2a 20 6f 66 20 74 79 70 65 20 22 5b 73 71 6c 69  * of type "[sqli
a8a0: 74 65 33 5f 76 66 73 5d 20 2a 2a 22 2e 20 20 54  te3_vfs] **".  T
a8b0: 68 69 73 20 6f 70 63 6f 64 65 73 20 77 69 6c 6c  his opcodes will
a8c0: 20 73 65 74 20 2a 58 0a 2a 2a 20 74 6f 20 61 20   set *X.** to a 
a8d0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74  pointer to the t
a8e0: 6f 70 2d 6c 65 76 65 6c 20 56 46 53 2e 29 5e 0a  op-level VFS.)^.
a8f0: 2a 2a 20 5e 57 68 65 6e 20 74 68 65 72 65 20 61  ** ^When there a
a900: 72 65 20 6d 75 6c 74 69 70 6c 65 20 56 46 53 20  re multiple VFS 
a910: 73 68 69 6d 73 20 69 6e 20 74 68 65 20 73 74 61  shims in the sta
a920: 63 6b 2c 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ck, this opcode 
a930: 66 69 6e 64 73 20 74 68 65 0a 2a 2a 20 75 70 70  finds the.** upp
a940: 65 72 2d 6d 6f 73 74 20 73 68 69 6d 20 6f 6e 6c  er-most shim onl
a950: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
a960: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a970: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
a980: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
a990: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
a9a0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
a9b0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
a9c0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
a9d0: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
a9e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a9f0: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
aa00: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
aa10: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
aa20: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
aa30: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
aa40: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
aa50: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
aa60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aa70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
aa80: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
aa90: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
aaa0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
aab0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
aac0: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
aad0: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
aae0: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
aaf0: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
ab00: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
ab10: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
ab20: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
ab30: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
ab40: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
ab50: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
ab60: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
ab70: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ab80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
ab90: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
aba0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
abb0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
abc0: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
abd0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
abe0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
abf0: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
ac00: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
ac10: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
ac20: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
ac30: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
ac40: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
ac50: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
ac60: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
ac70: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ac90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aca0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
acb0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
acc0: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
acd0: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
ace0: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
acf0: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ad00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ad10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ad20: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ad30: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
ad40: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
ad50: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
ad60: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
ad70: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
ad80: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
ad90: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
ada0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
adb0: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
adc0: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
add0: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
ade0: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
adf0: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
ae00: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
ae10: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
ae20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ae30: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ae40: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
ae50: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
ae60: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
ae70: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
ae80: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
ae90: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
aea0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
aeb0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
aec0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
aed0: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
aee0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
aef0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
af00: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
af10: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
af20: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
af30: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
af40: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
af50: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
af60: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
af70: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
af80: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
af90: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
afa0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
afb0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
afc0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
afd0: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
afe0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
aff0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
b000: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
b010: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
b020: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
b030: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
b040: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
b050: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
b060: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
b070: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
b080: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
b090: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
b0a0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
b0b0: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
b0c0: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
b0d0: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
b0e0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
b0f0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
b100: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
b110: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
b120: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
b130: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
b140: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
b150: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
b160: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
b170: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
b180: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
b190: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
b1a0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
b1b0: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
b1c0: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
b1d0: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
b1e0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
b1f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
b200: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
b210: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
b220: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
b230: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
b240: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
b250: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
b260: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
b270: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b280: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
b290: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
b2a0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
b2b0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
b2c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
b2d0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
b2e0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
b2f0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
b300: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
b310: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
b320: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
b330: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
b340: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
b350: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
b360: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
b370: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
b380: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
b390: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
b3a0: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
b3b0: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
b3c0: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
b3d0: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
b3e0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
b3f0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
b400: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
b410: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
b420: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
b430: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
b440: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
b450: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
b460: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b470: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b480: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b490: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
b4a0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b4b0: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
b4c0: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
b4d0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b4e0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
b4f0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
b500: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
b510: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
b520: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b530: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
b540: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
b550: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
b560: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
b570: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
b580: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
b590: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
b5a0: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
b5b0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
b5c0: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
b5d0: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
b5e0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
b5f0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
b600: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
b610: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
b620: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
b630: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
b640: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
b650: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
b660: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
b670: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
b680: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
b690: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
b6a0: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
b6b0: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
b6c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b6d0: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
b6e0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b6f0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
b700: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
b710: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
b720: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
b730: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
b740: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
b750: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
b760: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
b770: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
b780: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
b790: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
b7a0: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
b7b0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b7c0: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
b7d0: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
b7e0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
b7f0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
b800: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
b810: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
b820: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b830: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
b840: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
b850: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
b860: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
b870: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
b880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
b890: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
b8a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
b8b0: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
b8c0: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
b8d0: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
b8e0: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
b8f0: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
b900: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
b910: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
b920: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
b930: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
b940: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
b950: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
b960: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
b970: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
b980: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
b990: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b9a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b9b0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
b9c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b9d0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b9e0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b9f0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
ba00: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
ba10: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
ba20: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
ba30: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
ba40: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
ba50: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
ba60: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
ba70: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
ba80: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
ba90: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
baa0: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
bab0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
bac0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
bad0: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
bae0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
baf0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bb00: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
bb10: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
bb20: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
bb30: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
bb40: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
bb50: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
bb60: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
bb70: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
bb80: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
bb90: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
bba0: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
bbb0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
bbc0: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
bbd0: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
bbe0: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
bbf0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
bc00: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
bc10: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
bc20: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
bc30: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
bc40: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
bc50: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
bc60: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
bc70: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
bc80: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bc90: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
bca0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
bcb0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
bcc0: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
bcd0: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
bce0: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
bcf0: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
bd00: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
bd10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
bd20: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
bd30: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
bd40: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
bd50: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
bd60: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
bd70: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
bd80: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
bd90: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
bda0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
bdb0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
bdc0: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f   opcode.  .** </
bdd0: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
bde0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
bdf0: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
be00: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
be10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
be20: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
be30: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
be40: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
be50: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
be60: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
be70: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
be80: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
be90: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
bea0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
beb0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
bec0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
bed0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
bee0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
bef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf00: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
bf10: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
bf20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf30: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
bf40: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
bf50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf60: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
bf70: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
bf80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf90: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
bfa0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
bfb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bfc0: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
bfd0: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
bfe0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bff0: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
c000: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
c010: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c020: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
c030: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
c040: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
c050: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
c060: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
c070: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
c080: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
c090: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
c0a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
c0b0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
c0c0: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
c0d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
c0e0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
c0f0: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
c100: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c120: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
c130: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
c140: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
c150: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
c160: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c180: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
c190: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
c1a0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
c1b0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
c1c0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
c1d0: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
c1e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1f0: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
c200: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
c210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c220: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
c230: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
c240: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c250: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20  NTL_RBU         
c260: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 23 64             26.#d
c270: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c280: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 20 20  TL_VFS_POINTER  
c290: 20 20 20 20 20 20 20 20 20 20 32 37 0a 0a 2f 2a            27../*
c2a0: 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d 65   deprecated name
c2b0: 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  s */.#define SQL
c2c0: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
c2d0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
c2e0: 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b  E_FCNTL_GET_LOCK
c2f0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
c300: 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43  e SQLITE_SET_LOC
c310: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
c320: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54  SQLITE_FCNTL_SET
c330: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23  _LOCKPROXYFILE.#
c340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
c350: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
c360: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c370: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f  L_LAST_ERRNO.../
c380: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
c390: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
c3a0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
c3b0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
c3c0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
c3d0: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
c3e0: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
c3f0: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
c400: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
c410: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
c420: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
c430: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
c440: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
c450: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
c460: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
c470: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
c480: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
c490: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
c4a0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
c4b0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
c4c0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
c4d0: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
c4e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
c4f0: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
c500: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
c510: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
c520: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
c530: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
c540: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c550: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
c560: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
c570: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
c580: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
c590: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
c5a0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
c5b0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
c5c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
c5d0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
c5e0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
c5f0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
c600: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
c610: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
c620: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
c630: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
c640: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
c650: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
c660: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
c670: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
c680: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
c690: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
c6a0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
c6b0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
c6c0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
c6d0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
c6e0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
c6f0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
c700: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
c710: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
c720: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
c730: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
c740: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
c750: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
c760: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
c770: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
c780: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
c790: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
c7a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
c7b0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
c7c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
c7d0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
c7e0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
c7f0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
c800: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
c810: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
c820: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
c830: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
c840: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
c850: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
c860: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
c870: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
c880: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
c890: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
c8a0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
c8b0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
c8c0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
c8d0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
c8e0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
c8f0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
c900: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
c910: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
c920: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
c930: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
c940: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
c950: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
c960: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
c970: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
c980: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c990: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
c9a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
c9b0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
c9c0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
c9d0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
c9e0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
c9f0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
ca00: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
ca10: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
ca20: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
ca30: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
ca40: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
ca50: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
ca60: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
ca70: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
ca80: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
ca90: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
caa0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
cab0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
cac0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
cad0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
cae0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
caf0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
cb00: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
cb10: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
cb20: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
cb30: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
cb40: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
cb50: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
cb60: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
cb70: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
cb80: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
cb90: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
cba0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
cbb0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
cbc0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
cbd0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
cbe0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
cbf0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
cc00: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
cc10: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
cc20: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
cc30: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cc40: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
cc50: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
cc60: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
cc70: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
cc80: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
cc90: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
cca0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
ccb0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
ccc0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
ccd0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
cce0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
ccf0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
cd00: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
cd10: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
cd20: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
cd30: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
cd40: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
cd50: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
cd60: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
cd70: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
cd80: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
cd90: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
cda0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
cdb0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
cdc0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cdd0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
cde0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
cdf0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
ce00: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
ce10: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
ce20: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
ce30: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
ce40: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
ce50: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
ce60: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
ce70: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
ce80: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
ce90: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
cea0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
ceb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
cec0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
ced0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
cee0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
cef0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
cf00: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
cf10: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
cf20: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
cf30: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
cf40: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
cf50: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
cf60: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
cf70: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
cf80: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
cf90: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
cfa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
cfb0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
cfc0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
cfd0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
cfe0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
cff0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
d000: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
d010: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
d020: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
d030: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
d040: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
d050: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
d060: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
d070: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
d080: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
d090: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
d0a0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
d0b0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
d0c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d0d0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
d0e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d0f0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
d100: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
d110: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
d120: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d130: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
d140: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
d150: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
d160: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
d170: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d180: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
d190: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d1a0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
d1b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d1c0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
d1d0: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
d1e0: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
d1f0: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
d200: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
d210: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
d220: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
d230: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
d240: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
d250: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
d260: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
d270: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
d280: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
d290: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
d2a0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
d2b0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
d2c0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
d2d0: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
d2e0: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
d2f0: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
d300: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
d310: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
d320: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
d330: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
d340: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
d350: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
d360: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
d370: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
d380: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
d390: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
d3a0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
d3b0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
d3c0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
d3d0: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
d3e0: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
d3f0: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
d400: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
d410: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
d420: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
d430: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
d440: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
d450: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d460: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
d470: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d480: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
d490: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
d4a0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
d4b0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
d4c0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
d4d0: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
d4e0: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
d4f0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
d500: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d510: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
d520: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
d530: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
d540: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
d550: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
d560: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
d570: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
d580: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
d590: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
d5a0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
d5b0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
d5c0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
d5d0: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
d5e0: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
d5f0: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
d600: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
d610: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
d620: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
d630: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
d640: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
d650: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
d660: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
d670: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
d680: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
d690: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
d6a0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
d6b0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
d6c0: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
d6d0: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
d6e0: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
d6f0: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
d700: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
d710: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
d720: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
d730: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
d740: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
d750: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
d760: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
d770: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
d780: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
d790: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
d7a0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
d7b0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
d7c0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
d7d0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
d7e0: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
d7f0: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
d800: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
d810: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
d820: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
d830: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
d840: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
d850: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
d860: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
d870: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
d880: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
d890: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
d8a0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
d8b0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
d8c0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
d8d0: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
d8e0: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
d8f0: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
d900: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d910: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
d920: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
d930: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
d940: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
d950: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
d960: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
d970: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
d980: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
d990: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
d9a0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
d9b0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
d9c0: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
d9d0: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d9e0: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
d9f0: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
da00: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
da10: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
da20: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
da30: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
da40: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
da50: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
da60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
da70: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
da80: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
da90: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
daa0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
dab0: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
dac0: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
dad0: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
dae0: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
daf0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
db00: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
db10: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
db20: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
db30: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
db40: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
db50: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
db60: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
db70: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
db80: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
db90: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dba0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
dbb0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
dbc0: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
dbd0: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
dbe0: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
dbf0: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
dc00: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
dc10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
dc20: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
dc30: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
dc40: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
dc50: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
dc60: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
dc70: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
dc80: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
dc90: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
dca0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
dcb0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
dcc0: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
dcd0: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
dce0: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
dcf0: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
dd00: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
dd10: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
dd20: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
dd30: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
dd40: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
dd50: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
dd60: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
dd70: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
dd80: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
dd90: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
dda0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
ddb0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
ddc0: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
ddd0: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
dde0: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
ddf0: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
de00: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
de10: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
de20: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
de30: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
de40: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
de50: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
de60: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
de70: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
de80: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
de90: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
dea0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
deb0: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
dec0: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
ded0: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
dee0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
def0: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
df00: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
df10: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
df20: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
df30: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
df40: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
df50: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
df60: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
df70: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
df80: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
df90: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
dfa0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
dfb0: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
dfc0: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
dfd0: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
dfe0: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
dff0: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
e000: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
e010: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
e020: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
e030: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
e040: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
e050: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
e060: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
e070: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
e080: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
e090: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
e0a0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
e0b0: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
e0c0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
e0d0: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
e0e0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
e0f0: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
e100: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
e110: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
e120: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
e130: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
e140: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
e150: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
e160: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
e170: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
e180: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
e190: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
e1a0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
e1b0: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
e1c0: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
e1d0: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
e1e0: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
e1f0: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
e200: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
e210: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
e220: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
e230: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
e240: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
e250: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
e260: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
e270: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
e280: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
e290: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
e2a0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
e2b0: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
e2c0: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
e2d0: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
e2e0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
e2f0: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
e300: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
e310: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
e320: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
e330: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
e340: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
e350: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
e360: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
e370: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
e380: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
e390: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
e3a0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
e3b0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
e3c0: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
e3d0: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
e3e0: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
e3f0: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
e400: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
e410: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
e420: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
e430: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
e440: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
e450: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
e460: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
e470: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
e480: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
e490: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
e4a0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
e4b0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
e4c0: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
e4d0: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
e4e0: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
e4f0: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
e500: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
e510: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e520: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
e530: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
e540: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
e550: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
e560: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
e570: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
e580: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
e590: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
e5a0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
e5b0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e5c0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
e5d0: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
e5e0: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
e5f0: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
e600: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
e610: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e620: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e630: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
e640: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
e650: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e660: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e670: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
e680: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
e690: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
e6a0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
e6b0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e6c0: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
e6d0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
e6e0: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
e6f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
e700: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
e710: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
e720: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
e730: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
e740: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
e750: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
e760: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
e770: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
e780: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
e790: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
e7a0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
e7b0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
e7c0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
e7d0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
e7e0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e7f0: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
e800: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
e810: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
e820: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
e830: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
e840: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
e850: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
e860: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
e870: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e880: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
e890: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
e8a0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
e8b0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
e8c0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e8d0: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
e8e0: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
e8f0: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
e900: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
e910: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
e920: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
e930: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
e940: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
e950: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
e960: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
e970: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
e980: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
e990: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
e9a0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
e9b0: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
e9c0: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
e9d0: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
e9e0: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
e9f0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ea00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
ea10: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
ea20: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
ea30: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
ea40: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
ea50: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
ea60: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
ea70: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
ea80: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
ea90: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
eaa0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
eab0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
eac0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
ead0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
eae0: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
eaf0: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
eb00: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
eb10: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
eb20: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
eb30: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
eb40: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
eb50: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
eb60: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
eb70: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
eb80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eb90: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
eba0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
ebb0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ebc0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
ebd0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
ebe0: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
ebf0: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
ec00: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
ec10: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
ec20: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
ec30: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
ec40: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
ec50: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
ec60: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
ec70: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
ec80: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec90: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
eca0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
ecb0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
ecc0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
ecd0: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
ece0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ecf0: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
ed00: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ed10: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
ed20: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
ed30: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
ed40: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
ed50: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
ed60: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
ed70: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
ed80: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
ed90: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
eda0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
edb0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
edc0: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
edd0: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
ede0: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
edf0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
ee00: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
ee10: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
ee20: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
ee30: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
ee40: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
ee50: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ee60: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
ee70: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
ee80: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
ee90: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
eea0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
eeb0: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
eec0: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
eed0: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
eee0: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
eef0: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
ef00: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
ef10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
ef20: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
ef30: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
ef40: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ef50: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
ef60: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
ef70: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
ef80: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
ef90: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
efa0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
efb0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
efc0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
efd0: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
efe0: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
eff0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
f000: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
f010: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
f020: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
f030: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
f040: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f050: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
f060: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
f070: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
f080: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
f090: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
f0a0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
f0b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
f0c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
f0d0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
f0e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
f0f0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
f100: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
f110: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f120: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
f130: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f140: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
f150: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
f160: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
f170: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
f180: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
f190: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
f1a0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
f1b0: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
f1c0: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
f1d0: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
f1e0: 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
f1f0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
f200: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
f210: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
f220: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
f230: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f240: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
f250: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
f260: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
f270: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
f280: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
f290: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
f2a0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
f2b0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
f2c0: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
f2d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f2e0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
f2f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f300: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
f310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f320: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
f330: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
f340: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
f350: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
f360: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
f370: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
f380: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
f390: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
f3a0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
f3b0: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
f3c0: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
f3d0: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
f3e0: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
f3f0: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
f400: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
f410: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
f420: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
f430: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
f440: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
f450: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
f460: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
f470: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
f480: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
f490: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
f4a0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
f4b0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
f4c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
f4d0: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
f4e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
f4f0: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
f500: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
f510: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
f520: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
f530: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
f540: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
f550: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
f560: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
f570: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
f580: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
f590: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
f5a0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
f5b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
f5c0: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
f5d0: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
f5e0: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
f5f0: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
f600: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
f610: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
f620: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
f630: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
f640: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
f650: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
f660: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f670: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
f680: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
f690: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
f6a0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
f6b0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
f6c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f6d0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
f6e0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
f6f0: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f700: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
f710: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
f720: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
f730: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f740: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
f750: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
f760: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
f770: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f780: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
f790: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f7a0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
f7b0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
f7c0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
f7d0: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
f7e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
f7f0: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
f800: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f810: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
f820: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f830: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f840: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
f850: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
f860: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
f870: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
f880: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f890: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
f8a0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
f8b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f8c0: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
f8d0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
f8e0: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
f8f0: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
f900: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
f910: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
f920: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
f930: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
f940: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
f950: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
f960: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
f970: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
f980: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
f990: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
f9a0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
f9b0: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
f9c0: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
f9d0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
f9e0: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
f9f0: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
fa00: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fa10: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
fa20: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fa30: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
fa40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa50: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
fa60: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fa70: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
fa80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa90: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
faa0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
fab0: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
fac0: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
fad0: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
fae0: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
faf0: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
fb00: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
fb10: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
fb20: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
fb30: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
fb40: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
fb50: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
fb60: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
fb70: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
fb80: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
fb90: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
fba0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
fbb0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
fbc0: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
fbd0: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
fbe0: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
fbf0: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
fc00: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
fc10: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
fc20: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
fc30: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
fc40: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
fc50: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
fc60: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
fc70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc80: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
fc90: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
fca0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
fcb0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
fcc0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
fcd0: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
fce0: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
fcf0: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
fd00: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
fd10: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
fd20: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
fd30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
fd40: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
fd50: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
fd60: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
fd70: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
fd80: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fd90: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
fda0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
fdb0: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
fdc0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fdd0: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
fde0: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
fdf0: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
fe00: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
fe10: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
fe20: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
fe30: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
fe40: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
fe50: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
fe60: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
fe70: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
fe80: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
fe90: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fea0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
feb0: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
fec0: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
fed0: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
fee0: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
fef0: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
ff00: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
ff10: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
ff20: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
ff30: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
ff40: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
ff50: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
ff60: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
ff70: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
ff80: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
ff90: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
ffa0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
ffb0: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
ffc0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
ffd0: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
ffe0: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
fff0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
10000 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
10010 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
10020 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
10030 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
10040 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
10050 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
10060 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
10070 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
10080 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
10090 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
100a0 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
100b0 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
100c0 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
100d0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
100e0 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
100f0 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
10100 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
10110 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
10120 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
10130 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
10140 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
10150 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
10160 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
10170 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10180 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
10190 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
101a0 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
101b0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
101c0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
101d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
101e0 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
101f0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
10200 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
10210 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
10220 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
10230 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
10240 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
10250 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
10260 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
10270 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
10280 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
10290 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
102a0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
102b0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
102c0 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
102d0 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
102e0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
102f0 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
10300 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
10310 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
10320 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
10330 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
10340 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
10350 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
10360 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
10370 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
10380 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
10390 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
103a0 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
103b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
103c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
103d0 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
103e0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
103f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
10400 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
10410 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
10420 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
10430 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
10440 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
10450 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
10460 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
10470 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
10480 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10490 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
104a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
104b0 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
104c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
104d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
104e0 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53  hutdown(void);.S
104f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
10500 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
10510 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
10520 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
10530 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
10540 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  L sqlite3_os_end
10550 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
10560 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10570 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
10580 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
10590 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
105a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
105b0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
105c0 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
105d0 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
105e0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
105f0 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
10600 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
10610 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
10620 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
10630 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
10640 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
10650 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
10660 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
10670 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
10680 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
10690 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
106a0 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
106b0 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
106c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
106d0 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
106e0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71  .**.** <b>The sq
106f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10700 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
10710 74 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20  threadsafe. The 
10720 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d  application.** m
10730 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20  ust ensure that 
10740 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  no other SQLite 
10750 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
10760 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a  nvoked by other.
10770 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65  ** threads while
10780 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10790 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62  ) is running.</b
107a0 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  >.**.** The sqli
107b0 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
107c0 65 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e  erface.** may on
107d0 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72  ly be invoked pr
107e0 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69  ior to library i
107f0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73  nitialization us
10800 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
10810 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72  initialize()] or
10820 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20   after shutdown 
10830 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  by [sqlite3_shut
10840 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20  down()]..** ^If 
10850 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10860 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72   is called after
10870 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
10880 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f  lize()] and befo
10890 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  re.** [sqlite3_s
108a0 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20  hutdown()] then 
108b0 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53  it will return S
108c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a  QLITE_MISUSE..**
108d0 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20   Note, however, 
108e0 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f  that ^sqlite3_co
108f0 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61  nfig() can be ca
10900 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  lled as part of 
10910 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
10920 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c  ation of an appl
10930 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10940 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74  [sqlite3_os_init
10950 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  ()]..**.** The f
10960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10970 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10980 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a  ) is an integer.
10990 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  ** [configuratio
109a0 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64  n option] that d
109b0 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61  etermines.** wha
109c0 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51  t property of SQ
109d0 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f  Lite is to be co
109e0 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65  nfigured.  Subse
109f0 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a  quent arguments.
10a00 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ** vary dependin
10a10 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67  g on the [config
10a20 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a  uration option].
10a30 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
10a40 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
10a50 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72  ^When a configur
10a60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
10a70 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  set, sqlite3_con
10a80 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53  fig() returns [S
10a90 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49  QLITE_OK]..** ^I
10aa0 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20  f the option is 
10ab0 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74  unknown or SQLit
10ac0 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73  e is unable to s
10ad0 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a  et the option.**
10ae0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
10af0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e  ne returns a non
10b00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
10b10 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  e]..*/.SQLITE_AP
10b20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45  I int SQLITE_CDE
10b30 43 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  CL sqlite3_confi
10b40 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
10b50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
10b60 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
10b70 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
10b80 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
10b90 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
10ba0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
10bb0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10bc0 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
10bd0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
10be0 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
10bf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
10c00 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
10c10 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
10c20 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
10c30 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
10c40 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
10c50 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
10c60 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10c70 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
10c80 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
10c90 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
10ca0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10cb0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
10cc0 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
10cd0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10ce0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
10cf0 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
10d00 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
10d10 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
10d20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
10d30 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
10d40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
10d50 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
10d60 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
10d70 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
10d80 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
10d90 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
10da0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
10db0 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
10dc0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10dd0 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
10de0 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
10df0 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
10e00 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
10e10 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
10e20 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10e30 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
10e40 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
10e50 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
10e60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10e70 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10e80 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
10e90 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
10ea0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
10eb0 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
10ec0 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
10ed0 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
10ee0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10ef0 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10f00 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
10f10 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
10f20 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
10f30 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
10f40 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
10f50 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
10f60 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10f70 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10f80 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10f90 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
10fa0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10fb0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
10fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10fd0 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
10fe0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10ff0 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
11000 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
11010 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
11020 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
11030 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
11040 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
11050 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
11060 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
11070 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
11080 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
11090 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
110a0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
110b0 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
110c0 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
110d0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
110e0 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
110f0 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
11100 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
11110 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
11120 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
11130 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
11140 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
11150 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
11160 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
11170 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
11180 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11190 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
111a0 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
111b0 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
111c0 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
111d0 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
111e0 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
111f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
11200 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
11210 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
11220 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
11230 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
11240 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
11250 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
11260 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
11270 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
11280 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
11290 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
112a0 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
112b0 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
112c0 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
112d0 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
112e0 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
112f0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
11300 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
11310 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
11320 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
11330 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
11340 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
11350 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
11360 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
11370 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
11380 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
11390 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
113a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
113b0 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
113c0 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
113d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
113e0 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
113f0 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
11400 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
11410 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
11420 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
11430 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
11440 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
11450 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
11460 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
11470 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
11480 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
11490 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
114a0 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
114b0 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
114c0 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
114d0 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
114e0 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
114f0 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
11500 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
11510 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11520 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
11530 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
11540 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
11550 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
11560 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
11570 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
11580 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
11590 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
115a0 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
115b0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
115c0 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
115d0 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
115e0 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
115f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11600 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
11610 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
11620 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
11630 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
11640 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
11650 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
11660 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
11670 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
11680 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
11690 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
116a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
116b0 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
116c0 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
116d0 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
116e0 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
116f0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
11700 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
11710 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
11720 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
11730 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
11740 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
11750 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
11760 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
11770 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
11780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
11790 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
117a0 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
117b0 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
117c0 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
117d0 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
117e0 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
117f0 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
11800 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
11810 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
11820 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
11830 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11840 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
11850 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
11860 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
11870 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
11880 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
11890 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
118a0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
118b0 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
118c0 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
118d0 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
118e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
118f0 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
11900 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
11910 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
11920 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
11930 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
11940 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
11950 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
11960 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
11970 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
11980 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11990 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
119a0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
119b0 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
119c0 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
119d0 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
119e0 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
119f0 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
11a00 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
11a10 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
11a20 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
11a30 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
11a40 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
11a50 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
11a60 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11a70 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11a80 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11a90 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11aa0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11ab0 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11ac0 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11ad0 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11ae0 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11af0 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11b00 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
11b10 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
11b20 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
11b30 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11b40 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
11b50 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
11b60 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11b70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11b80 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
11b90 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
11ba0 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
11bb0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11bc0 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
11bd0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
11be0 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11bf0 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11c00 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
11c10 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11c20 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
11c30 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11c40 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
11c50 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
11c60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11c70 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11c80 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
11c90 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
11ca0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11cb0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
11cc0 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
11cd0 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
11ce0 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11cf0 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11d00 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
11d10 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
11d20 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
11d30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
11d40 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
11d50 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
11d60 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11d70 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11d80 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
11d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11da0 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
11db0 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
11dc0 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
11dd0 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
11de0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11df0 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11e00 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
11e10 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11e20 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
11e30 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
11e40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
11e50 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
11e60 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11e70 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11e80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11e90 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
11ea0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
11eb0 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
11ec0 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
11ed0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11ee0 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11ef0 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11f00 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
11f10 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
11f20 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
11f30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
11f40 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
11f50 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
11f60 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11f70 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11f80 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
11f90 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
11fa0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
11fb0 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
11fc0 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
11fd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11fe0 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11ff0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
12000 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12010 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
12020 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12030 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
12040 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12050 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12060 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
12070 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
12080 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
12090 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
120a0 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
120b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
120c0 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
120d0 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
120e0 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
120f0 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
12100 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
12110 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
12120 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
12130 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12140 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12150 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12160 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12170 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12180 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12190 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
121a0 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
121b0 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
121c0 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
121d0 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
121e0 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
121f0 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
12200 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12210 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
12220 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12230 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
12240 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
12250 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
12260 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12270 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12280 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
12290 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
122a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
122b0 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
122c0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
122d0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
122e0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
122f0 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
12300 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
12310 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
12320 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
12330 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12340 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
12350 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12360 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12370 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12380 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
12390 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
123a0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
123b0 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
123c0 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
123d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
123e0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
123f0 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
12400 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
12410 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
12420 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
12430 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
12440 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
12450 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
12460 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
12470 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
12480 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
12490 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
124a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
124b0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
124c0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
124d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
124e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
124f0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
12500 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
12510 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
12520 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
12530 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
12540 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
12550 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
12560 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
12570 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12580 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
12590 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
125a0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
125b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
125c0 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
125d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
125e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
125f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
12600 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
12610 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12620 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
12630 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
12640 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
12650 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
12660 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
12670 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
12680 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
12690 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
126a0 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
126b0 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
126c0 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
126d0 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
126e0 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
126f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12700 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12710 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
12720 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
12730 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
12740 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
12750 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12760 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
12770 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
12780 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
12790 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
127a0 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
127b0 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
127c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
127e0 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
127f0 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
12800 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
12810 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
12820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12830 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
12840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12850 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
12860 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
12870 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
12880 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12890 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
128a0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
128b0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
128c0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
128d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
128e0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
128f0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12900 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
12910 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12920 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
12930 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
12940 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
12950 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12960 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
12970 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12980 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
12990 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
129a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
129b0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
129c0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
129d0 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
129e0 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
129f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12a00 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12a10 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12a20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
12a30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12a40 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12a50 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12a60 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
12a70 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
12a80 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
12a90 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
12aa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12ab0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  on routines to b
12ac0 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20  e used in place 
12ad0 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79  of.** the memory
12ae0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12af0 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20  ines built into 
12b00 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74  SQLite.)^ ^SQLit
12b10 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f  e makes.** its o
12b20 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
12b30 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  of the content o
12b40 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12b50 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12b60 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20  cture.** before 
12b70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
12b80 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75  fig()] call retu
12b90 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  rns.</dd>.**.** 
12ba0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12bb0 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  GETMALLOC]] <dt>
12bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12bd0 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  TMALLOC</dt>.** 
12be0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12bf0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12c00 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  OC option takes 
12c10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12c20 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20  t which.** is a 
12c30 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12c40 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
12c50 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12c60 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
12c70 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  * The [sqlite3_m
12c80 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
12c90 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12ca0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12cb0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
12cc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12cd0 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12ce0 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12cf0 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12d00 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12d10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12d20 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12d30 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
12d40 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
12d50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
12d60 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
12d70 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
12d80 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
12d90 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12da0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12db0 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
12dc0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12dd0 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
12de0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12df0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74  IG_MEMSTATUS opt
12e00 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65  ion takes single
12e10 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
12e20 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70  e int,.** interp
12e30 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65  reted as a boole
12e40 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65  an, which enable
12e50 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
12e60 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a  e collection of.
12e70 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
12e80 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e  tion statistics.
12e90 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
12ea0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12eb0 74 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  tics are.** disa
12ec0 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77  bled, the follow
12ed0 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
12ee0 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12ef0 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12f00 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12f10 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12f20 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12f30 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12f40 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12f50 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
12f60 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
12f70 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
12f80 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
12f90 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75  us64()].**   </u
12fa0 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20  l>)^.** ^Memory 
12fb0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
12fc0 73 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65  stics are enable
12fd0 64 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c  d by default unl
12fe0 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a  ess SQLite is.**
12ff0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
13000 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d  SQLITE_DEFAULT_M
13010 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77  EMSTATUS]=0 in w
13020 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79  hich case memory
13030 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  .** allocation s
13040 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69  tatistics are di
13050 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
13060 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  t..** </dd>.**.*
13070 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13080 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e  G_SCRATCH]] <dt>
13090 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
130a0 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RATCH</dt>.** <d
130b0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
130c0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70  ONFIG_SCRATCH op
130d0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
130e0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
130f0 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51  uffer.** that SQ
13100 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
13110 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
13120 20 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68    ^(There are th
13130 72 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ree arguments.**
13140 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13150 47 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f  G_SCRATCH:  A po
13160 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a  inter an 8-byte.
13170 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72  ** aligned memor
13180 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68  y buffer from wh
13190 69 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20  ich the scratch 
131a0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c  allocations will
131b0 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68   be.** drawn, th
131c0 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73  e size of each s
131d0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
131e0 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  n (sz),.** and t
131f0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
13200 72 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c  r of scratch all
13210 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a  ocations (N).)^.
13220 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
13230 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
13240 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
13250 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
13260 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
13270 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13280 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
13290 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65  ite will not use
132a0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73   more than one s
132b0 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
132c0 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53  er thread..** ^S
132d0 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72  QLite will never
132e0 20 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74   request a scrat
132f0 63 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69  ch buffer that i
13300 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a  s more than 6.**
13310 20 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62   times the datab
13320 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a  ase page size..*
13330 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65  * ^If SQLite nee
13340 64 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f  ds needs additio
13350 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  nal.** scratch m
13360 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61  emory beyond wha
13370 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
13380 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   this configurat
13390 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ion option, then
133a0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
133b0 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20  lloc()] will be 
133c0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
133d0 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64  he memory needed
133e0 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  .<p>.** ^When th
133f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72  e application pr
13400 6f 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e  ovides any amoun
13410 74 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d  t of scratch mem
13420 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  ory using.** SQL
13430 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13440 43 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64  CH, SQLite avoid
13450 73 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61  s unnecessary la
13460 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rge.** [sqlite3_
13470 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f  malloc|heap allo
13480 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69  cations]..** Thi
13490 73 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73  s can help [Robs
134a0 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74  on proof|prevent
134b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
134c0 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65  on failures] due
134d0 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67   to heap.** frag
134e0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77  mentation in low
134f0 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64  -memory embedded
13500 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64   systems..** </d
13510 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13520 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13530 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
13540 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13550 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
13560 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13570 5f 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f  _PAGECACHE optio
13580 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 6d 65  n specifies a me
13590 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61  mory pool.** tha
135a0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
135b0 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
135c0 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
135d0 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
135e0 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
135f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a  ementation.  .**
13600 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
13610 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 61 20  ion option is a 
13620 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61 70 70 6c  no-op if an appl
13630 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
13640 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
13650 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
13660 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
13670 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13680 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65  CACHE2]..** ^The
13690 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
136a0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
136b0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
136c0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
136d0 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
136e0 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65 6d 29 2c  d memory (pMem),
136f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
13700 68 20 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e  h page cache lin
13710 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74  e (sz),.** and t
13720 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 61 63  he number of cac
13730 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a  he lines (N)..**
13740 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
13750 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
13760 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
13770 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
13780 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
13790 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
137a0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
137b0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
137c0 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
137d0 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
137e0 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
137f0 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13800 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13810 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
13820 69 6e 65 64 20 75 73 69 6e 67 20 5b 53 51 4c 49  ined using [SQLI
13830 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
13840 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20  _HDRSZ]..** ^It 
13850 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
13860 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
13870 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f  ed memory,.** fo
13880 72 20 74 68 65 20 73 7a 20 70 61 72 61 6d 65 74  r the sz paramet
13890 65 72 20 74 6f 20 62 65 20 6c 61 72 67 65 72 20  er to be larger 
138a0 74 68 61 6e 20 6e 65 63 65 73 73 61 72 79 2e 20  than necessary. 
138b0 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20 61 72 67   The pMem.** arg
138c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 65 69  ument must be ei
138d0 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
138e0 74 65 72 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ter or a pointer
138f0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
13900 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f   aligned block o
13910 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61 74 20 6c  f memory of at l
13920 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 2c  east sz*N bytes,
13930 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a 20 73 75   otherwise.** su
13940 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
13950 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
13960 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d 20 69 73  ** ^When pMem is
13970 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74   not NULL, SQLit
13980 65 20 77 69 6c 6c 20 73 74 72 69 76 65 20 74 6f  e will strive to
13990 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
139a0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74 6f 20 73  provided.** to s
139b0 61 74 69 73 66 79 20 70 61 67 65 20 63 61 63 68  atisfy page cach
139c0 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c 69 6e 67  e needs, falling
139d0 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c 69 74 65   back to [sqlite
139e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a  3_malloc()] if.*
139f0 2a 20 61 20 70 61 67 65 20 63 61 63 68 65 20 6c  * a page cache l
13a00 69 6e 65 20 69 73 20 6c 61 72 67 65 72 20 74 68  ine is larger th
13a10 61 6e 20 73 7a 20 62 79 74 65 73 20 6f 72 20 69  an sz bytes or i
13a20 66 20 61 6c 6c 20 6f 66 20 74 68 65 20 70 4d 65  f all of the pMe
13a30 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 65  m buffer.** is e
13a40 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20 5e 49 66  xhausted..** ^If
13a50 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c 20 61 6e   pMem is NULL an
13a60 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  d N is non-zero,
13a70 20 74 68 65 6e 20 65 61 63 68 20 64 61 74 61 62   then each datab
13a80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
13a90 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69 74 69 61  * does an initia
13aa0 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f  l bulk allocatio
13ab0 6e 20 66 6f 72 20 70 61 67 65 20 63 61 63 68 65  n for page cache
13ac0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20   memory.** from 
13ad0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13ae0 29 5d 20 73 75 66 66 69 63 69 65 6e 74 20 66 6f  )] sufficient fo
13af0 72 20 4e 20 63 61 63 68 65 20 6c 69 6e 65 73 20  r N cache lines 
13b00 69 66 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65  if N is positive
13b10 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30 32 34 2a   or.** of -1024*
13b20 4e 20 62 79 74 65 73 20 69 66 20 4e 20 69 73 20  N bytes if N is 
13b30 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e 49 66 20  negative, . ^If 
13b40 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
13b50 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
13b60 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
13b70 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13b80 64 20 62 79 20 74 68 65 20 69 6e 69 74 69 61 6c  d by the initial
13b90 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  .** allocation, 
13ba0 74 68 65 6e 20 53 51 4c 69 74 65 20 67 6f 65 73  then SQLite goes
13bb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
13bc0 6c 6f 63 28 29 5d 20 73 65 70 61 72 61 74 65 6c  loc()] separatel
13bd0 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 61 64  y for each.** ad
13be0 64 69 74 69 6f 6e 61 6c 20 63 61 63 68 65 20 6c  ditional cache l
13bf0 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ine. </dd>.**.**
13c00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13c10 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
13c20 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
13c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13c40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13c50 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13c60 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13c70 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13c80 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13c90 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13ca0 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
13cb0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
13cc0 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
13cd0 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
13ce0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
13cf0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
13d00 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
13d10 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
13d20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13d30 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
13d40 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13d50 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13d60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13d70 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13d80 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13d90 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13da0 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
13db0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
13dc0 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
13dd0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
13de0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
13df0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
13e00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13e10 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
13e20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
13e30 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13e40 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13e50 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13e60 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13e70 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13e80 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13e90 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13ea0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13eb0 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13ec0 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13ed0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
13ee0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
13ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13f00 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
13f10 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
13f20 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
13f30 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13f40 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13f50 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13f60 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13f70 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13f80 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13f90 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13fa0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13fb0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13fc0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13fd0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13fe0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
13ff0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
14000 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
14010 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
14020 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
14030 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
14040 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
14050 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
14060 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
14070 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
14080 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
14090 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
140a0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
140b0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
140c0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
140d0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
140e0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
140f0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
14100 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14110 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
14120 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
14130 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14140 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14150 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
14160 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
14170 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
14180 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
14190 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
141a0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
141b0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
141c0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
141d0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
141e0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
141f0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
14200 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
14210 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
14220 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
14230 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
14240 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
14250 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
14260 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
14270 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
14280 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
14290 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
142a0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
142b0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
142c0 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
142d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
142e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
142f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14300 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14310 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14320 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
14330 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
14340 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
14350 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
14360 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
14370 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
14380 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
14390 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
143a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
143b0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
143c0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
143d0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
143e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
143f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
14400 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
14410 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
14420 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
14430 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14440 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
14450 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14460 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14470 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14480 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
14490 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
144a0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
144b0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
144c0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
144d0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
144e0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
144f0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
14500 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
14510 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
14520 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
14530 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
14540 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
14550 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
14560 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14570 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
14580 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14590 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
145a0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
145b0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
145c0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
145d0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
145e0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
145f0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14600 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14610 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14620 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14630 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
14640 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14650 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14660 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14670 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14680 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14690 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
146a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
146b0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
146c0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
146d0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
146e0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
146f0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14700 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14710 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14720 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14730 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14740 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14750 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
14760 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14770 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14780 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14790 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
147a0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
147b0 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
147c0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
147d0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
147e0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
147f0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
14800 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
14810 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
14820 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
14830 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
14840 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
14850 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
14860 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
14870 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14880 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14890 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
148a0 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
148b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
148c0 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
148d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
148e0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
148f0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
14900 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14910 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14920 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
14930 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
14940 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14950 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14960 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14970 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14980 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14990 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
149a0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
149b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
149c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
149d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
149e0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
149f0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14a00 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
14a10 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
14a20 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
14a30 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
14a40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14a50 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14a60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14a70 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14a80 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14a90 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14aa0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14ab0 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
14ac0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14ad0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
14ae0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14af0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
14b00 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14b10 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14b20 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14b30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14b40 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14b50 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14b60 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14b70 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14b80 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14b90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14ba0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
14bb0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14bd0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
14be0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
14bf0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
14c00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14c10 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
14c20 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
14c30 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
14c40 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14c50 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14c60 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14c70 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14c80 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14c90 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14ca0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
14cb0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
14cc0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
14cd0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
14ce0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
14cf0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
14d00 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
14d10 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
14d20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
14d30 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
14d40 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14d50 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14d60 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14d70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14d90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14da0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
14db0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
14dc0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
14dd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14de0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14df0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
14e00 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
14e10 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14e20 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
14e30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14e40 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14e50 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14e60 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14e70 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14e80 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14e90 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14ea0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
14eb0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
14ec0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
14ed0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
14ee0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
14ef0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
14f00 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
14f10 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
14f20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
14f30 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
14f40 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14f50 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14f60 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14f70 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14f80 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14f90 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14fa0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14fb0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14fc0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14fd0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
14fe0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
14ff0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
15000 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
15010 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
15020 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
15030 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
15040 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
15050 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
15060 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
15070 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
15080 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
15090 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
150a0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
150b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
150c0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
150d0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
150e0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
150f0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15100 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
15110 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
15120 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
15130 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
15140 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
15150 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
15160 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
15170 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
15180 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
15190 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
151a0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
151b0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
151c0 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
151d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
151e0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
151f0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
15200 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
15210 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
15220 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
15230 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
15240 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
15250 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
15260 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
15270 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
15280 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
15290 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
152a0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
152b0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
152c0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
152d0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
152e0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
152f0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
15300 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
15310 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
15320 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
15330 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
15340 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
15350 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
15360 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
15370 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
15380 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
15390 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
153a0 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
153b0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
153c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
153d0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
153e0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
153f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15400 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
15410 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15420 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15430 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
15440 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15450 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15460 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
15470 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
15480 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
15490 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
154a0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
154b0 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
154c0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
154d0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
154e0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
154f0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
15500 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
15510 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
15520 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15530 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
15540 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
15550 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
15560 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
15570 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15580 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15590 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
155a0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
155b0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
155c0 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
155d0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
155e0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
155f0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
15600 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
15610 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
15620 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
15630 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
15640 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
15650 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
15660 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
15670 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15680 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15690 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
156a0 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
156b0 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
156c0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
156d0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
156e0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
156f0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
15700 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
15710 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15720 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
15730 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15740 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
15750 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15760 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
15770 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15780 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15790 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
157a0 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
157b0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
157c0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
157d0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
157e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
157f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
15800 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
15810 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15820 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15830 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
15840 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15850 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15860 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15870 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15880 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15890 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
158a0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
158b0 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
158c0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
158d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
158e0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
158f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
15900 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
15910 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
15920 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
15930 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
15940 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15950 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15960 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15970 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15980 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15990 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
159a0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
159b0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
159c0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
159d0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
159e0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
159f0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
15a00 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
15a10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15a20 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
15a30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15a40 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15a50 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15a60 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15a70 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15a80 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15a90 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15aa0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
15ab0 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
15ac0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
15ad0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
15ae0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
15af0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
15b00 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
15b10 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
15b20 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
15b30 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15b40 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15b50 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15b60 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15b70 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15b80 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15b90 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15ba0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
15bb0 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
15bc0 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
15bd0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
15be0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
15bf0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
15c00 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
15c10 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
15c20 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
15c30 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15c40 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15c50 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15c60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15c70 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15c80 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15c90 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15ca0 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
15cb0 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
15cc0 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
15cd0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
15ce0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
15cf0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
15d00 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
15d10 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
15d20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
15d30 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15d40 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15d50 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15d60 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15d70 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15d80 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15d90 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15da0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15db0 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
15dc0 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
15dd0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
15de0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
15df0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
15e00 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
15e10 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
15e20 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15e30 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15e40 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15e50 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15e60 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15e70 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15e80 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15e90 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15ea0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
15eb0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
15ec0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
15ed0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15ee0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
15ef0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
15f00 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
15f10 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
15f20 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
15f30 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15f40 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15f50 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15f70 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15f80 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15f90 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15fa0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15fb0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15fc0 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15fd0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15fe0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
15ff0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
16000 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
16010 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
16020 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
16030 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
16040 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
16050 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
16060 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
16070 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
16080 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
16090 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
160a0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
160b0 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
160c0 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
160d0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
160e0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
160f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16100 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
16110 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
16120 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
16130 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16140 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
16150 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
16160 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
16170 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
16180 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
16190 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
161a0 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
161b0 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
161c0 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
161d0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
161e0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
161f0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
16200 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
16210 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
16220 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
16230 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
16240 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
16250 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
16260 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16270 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
16280 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
16290 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
162a0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
162b0 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
162c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
162d0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
162e0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
162f0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
16300 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
16310 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
16320 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
16330 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
16340 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
16350 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
16360 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
16370 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
16380 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
16390 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
163a0 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
163b0 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
163c0 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
163d0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
163e0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
163f0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
16400 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
16410 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
16420 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
16430 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
16440 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
16450 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
16460 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
16470 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
16480 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
16490 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
164a0 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
164b0 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  lue..** </dl>.*/
164c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
164d0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
164e0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
164f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16500 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16510 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
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 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
16540 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
16550 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16560 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16570 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16580 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16590 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
165a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
165b0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
165c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
165d0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
165e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
165f0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
16600 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16610 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16620 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16630 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
16640 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16650 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16660 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16670 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16680 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16690 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
166a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
166b0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
166c0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
166d0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
166e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
166f0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
16700 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16710 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16720 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16730 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
16740 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
16750 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16760 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
16770 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16780 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16790 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
167a0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
167b0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
167c0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
167d0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
167e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
167f0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
16800 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
16810 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16820 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
16830 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
16840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16850 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
16860 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
16870 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16880 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16890 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
168a0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
168b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
168c0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
168d0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
168e0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
168f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16900 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
16910 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
16920 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16930 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16940 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16950 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
16960 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
16970 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16980 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
16990 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
169a0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
169b0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
169c0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
169d0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
169e0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
169f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16a00 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16a10 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
16a20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a40 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16a50 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
16a60 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
16a70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16a80 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
16a90 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
16aa0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
16ab0 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a */../*.** CAPI
16ac0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
16ad0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
16ae0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
16af0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
16b00 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
16b10 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
16b20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16b30 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
16b40 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
16b50 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16b60 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
16b70 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16b80 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16b90 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
16ba0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
16bb0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
16bc0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
16bd0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
16be0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
16bf0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
16c00 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
16c10 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
16c20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
16c30 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
16c40 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16c50 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16c60 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
16c70 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
16c80 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
16c90 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16ca0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
16cb0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
16cc0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
16cd0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
16ce0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
16cf0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
16d00 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
16d10 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16d20 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16d30 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16d40 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16d50 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16d60 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
16d70 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
16d80 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
16d90 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16da0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
16db0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
16dc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16dd0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
16de0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
16df0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
16e00 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16e10 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16e20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16e30 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16e40 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16e50 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16e60 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16e70 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16e80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16e90 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16ea0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
16eb0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
16ec0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
16ed0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
16ee0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
16ef0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
16f00 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
16f10 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
16f20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
16f30 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
16f40 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16f50 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16f60 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16f70 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
16f80 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
16f90 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16fa0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16fb0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
16fc0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16fd0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16fe0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16ff0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
17000 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
17010 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
17020 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
17030 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
17040 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
17050 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
17060 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
17070 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
17080 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
17090 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
170a0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
170b0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
170c0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
170d0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
170e0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
170f0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
17100 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
17110 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
17120 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
17130 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
17140 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
17150 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
17160 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
17170 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
17180 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
17190 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
171a0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
171b0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
171c0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
171d0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
171e0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
171f0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17200 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
17210 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
17220 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
17230 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
17240 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
17250 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
17260 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
17270 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
17280 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17290 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
172a0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
172b0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
172c0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
172d0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
172e0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
172f0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
17300 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
17310 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
17320 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
17330 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
17340 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
17350 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
17360 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
17370 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17380 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
17390 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
173a0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
173b0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
173c0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
173d0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
173e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
173f0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
17400 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
17410 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
17420 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
17430 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
17440 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17450 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
17460 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
17470 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
17480 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
17490 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
174a0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
174b0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
174c0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
174d0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
174e0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
174f0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
17500 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17510 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17520 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17530 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17540 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17550 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17560 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17570 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17580 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17590 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
175a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
175b0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
175c0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
175d0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
175e0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
175f0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
17600 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17610 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17620 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17630 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17640 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17650 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17660 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17670 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17680 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17690 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
176a0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
176b0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
176c0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
176d0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
176e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
176f0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
17700 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17710 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17720 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17730 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
17740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17750 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17760 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
17770 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
17780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17790 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
177a0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
177b0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
177c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
177d0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
177e0 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
177f0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
17800 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
17810 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
17820 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
17830 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
17840 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17850 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
17860 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
17870 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
17880 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
17890 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
178a0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
178b0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
178c0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
178d0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
178e0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
178f0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
17900 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
17910 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lity..*/.SQLITE_
17920 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
17930 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
17940 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
17950 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
17960 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
17970 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
17980 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
17990 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
179a0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
179b0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
179c0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
179d0 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
179e0 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
179f0 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
17a00 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
17a10 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
17a20 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
17a30 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
17a40 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
17a50 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
17a60 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
17a70 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
17a80 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
17a90 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
17aa0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
17ab0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
17ac0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
17ad0 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
17ae0 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
17af0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
17b00 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
17b10 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
17b20 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
17b30 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
17b40 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
17b50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
17b60 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17b70 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
17b80 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
17b90 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
17ba0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
17bb0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
17bc0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
17bd0 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
17be0 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
17bf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
17c00 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
17c10 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
17c20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
17c30 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
17c40 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
17c50 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
17c60 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
17c70 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
17c80 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17c90 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
17ca0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
17cb0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17cc0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
17cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
17ce0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
17cf0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
17d00 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
17d10 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
17d20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
17d30 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
17d40 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
17d50 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
17d60 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
17d70 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
17d80 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
17d90 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
17da0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
17db0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
17dc0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
17dd0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
17de0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
17df0 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
17e00 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
17e10 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
17e20 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17e30 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
17e40 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
17e50 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
17e60 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
17e70 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
17e80 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
17e90 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
17ea0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
17eb0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
17ec0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17ed0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
17ee0 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
17ef0 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
17f00 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
17f10 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
17f20 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
17f30 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
17f40 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
17f50 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
17f60 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
17f70 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
17f80 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
17f90 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
17fa0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
17fb0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
17fc0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
17fd0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
17fe0 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
17ff0 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
18000 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
18010 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
18020 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
18030 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
18040 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
18050 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
18060 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
18070 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
18080 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
18090 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
180a0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
180b0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
180c0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
180d0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
180e0 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
180f0 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
18100 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
18110 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
18120 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
18130 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
18140 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
18150 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
18160 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
18170 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
18180 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
18190 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
181a0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
181b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
181c0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
181d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
181e0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
181f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
18200 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
18210 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
18220 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
18230 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
18240 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18250 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
18260 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
18270 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
18280 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
18290 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
182a0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
182b0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
182c0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
182d0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
182e0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
182f0 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  LL sqlite3_last_
18300 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
18310 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18320 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
18330 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
18340 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
18350 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18360 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18370 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
18380 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
18390 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
183a0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
183b0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
183c0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
183d0 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
183e0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
183f0 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
18400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
18410 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
18420 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
18430 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
18440 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
18450 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
18460 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
18470 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
18480 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
18490 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
184a0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
184b0 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
184c0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
184d0 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
184e0 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
184f0 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
18500 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
18510 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
18520 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
18530 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
18540 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
18550 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
18560 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
18570 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
18580 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
18590 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
185a0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
185b0 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
185c0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
185d0 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
185e0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
185f0 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
18600 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18610 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
18620 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
18630 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
18640 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
18650 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
18660 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
18670 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
18680 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
18690 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
186a0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
186b0 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
186c0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
186d0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
186e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
186f0 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
18700 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
18710 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
18720 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
18730 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
18740 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
18750 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
18760 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
18770 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
18780 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
18790 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
187a0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
187b0 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
187c0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
187d0 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
187e0 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
187f0 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
18800 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
18810 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
18820 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
18830 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
18840 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
18850 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
18860 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
18870 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
18880 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
18890 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
188a0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
188b0 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
188c0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
188d0 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
188e0 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
188f0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18900 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
18910 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18920 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
18930 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
18940 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
18950 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
18960 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
18970 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
18980 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
18990 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
189a0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
189b0 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
189c0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
189d0 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
189e0 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
189f0 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
18a00 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
18a10 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
18a20 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
18a30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
18a40 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
18a50 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
18a60 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
18a70 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18a80 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
18a90 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
18aa0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
18ab0 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
18ac0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
18ad0 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
18ae0 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
18af0 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
18b00 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
18b10 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
18b20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
18b30 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
18b40 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
18b50 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
18b60 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
18b70 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
18b80 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
18b90 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18ba0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18bb0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
18bc0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
18bd0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18be0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18bf0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18c00 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
18c10 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18c20 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
18c30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18c40 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18c50 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
18c60 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18c70 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18c80 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18c90 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18ca0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18cb0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18cc0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
18cd0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18ce0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18cf0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
18d00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
18d10 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18d20 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
18d30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
18d40 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
18d50 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
18d60 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
18d70 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
18d80 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
18d90 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
18da0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
18db0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
18dc0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
18dd0 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
18de0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
18df0 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
18e00 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
18e10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18e20 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
18e30 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
18e40 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
18e50 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
18e60 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
18e70 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
18e80 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
18e90 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
18ea0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
18eb0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
18ec0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18ed0 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
18ee0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
18ef0 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
18f00 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
18f10 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
18f20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
18f30 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
18f40 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
18f50 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
18f60 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
18f70 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
18f80 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
18f90 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
18fa0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
18fb0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
18fc0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
18fd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
18fe0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
18ff0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
19000 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
19010 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
19020 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19030 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19040 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19050 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
19060 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
19070 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19080 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
19090 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
190a0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
190b0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
190c0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
190d0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
190e0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
190f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19100 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
19110 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
19120 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
19130 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
19140 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
19150 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
19160 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
19170 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
19180 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
19190 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
191a0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
191b0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
191c0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
191d0 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
191e0 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
191f0 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
19200 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
19210 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
19220 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
19230 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
19240 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
19250 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
19260 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
19270 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
19280 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
19290 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
192a0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
192b0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
192c0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
192d0 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
192e0 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
192f0 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
19300 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
19310 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
19320 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
19330 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
19340 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
19350 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
19360 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
19370 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
19380 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
19390 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
193a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
193b0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
193c0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
193d0 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
193e0 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
193f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
19400 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
19410 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
19420 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
19430 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
19440 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
19450 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
19460 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
19470 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
19480 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
19490 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
194a0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
194b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
194c0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
194d0 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
194e0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
194f0 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
19500 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
19510 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
19520 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
19530 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
19540 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
19550 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
19560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
19570 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19580 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
19590 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
195a0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
195b0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
195c0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
195d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
195e0 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
195f0 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
19600 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
19610 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
19620 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19630 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
19640 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
19650 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
19660 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
19670 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
19680 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
19690 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
196a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
196b0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
196c0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
196d0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
196e0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
196f0 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
19700 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
19710 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
19720 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
19730 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
19740 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
19750 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
19760 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
19770 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
19780 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
19790 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
197a0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
197b0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
197c0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
197d0 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
197e0 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
197f0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19800 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
19810 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
19820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19830 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
19840 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
19850 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
19860 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
19870 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
19880 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
19890 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
198a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
198b0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
198c0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
198d0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
198e0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
198f0 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
19900 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
19910 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
19920 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
19930 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
19940 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
19950 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
19960 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
19970 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
19980 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19990 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
199a0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
199b0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
199c0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
199d0 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
199e0 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
199f0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19a00 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
19a10 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
19a20 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
19a30 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
19a40 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
19a50 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
19a60 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
19a70 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
19a80 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
19a90 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
19aa0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
19ab0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
19ac0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
19ad0 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
19ae0 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
19af0 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
19b00 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
19b10 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
19b20 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
19b30 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
19b40 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
19b50 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
19b60 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
19b70 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
19b80 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
19b90 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
19ba0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
19bb0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
19bc0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
19bd0 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
19be0 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
19bf0 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
19c00 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
19c10 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
19c20 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
19c30 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
19c40 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
19c50 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
19c60 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
19c70 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
19c80 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
19c90 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
19ca0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
19cb0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
19cc0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
19cd0 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
19ce0 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
19cf0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
19d00 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
19d10 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
19d20 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
19d30 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
19d40 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
19d50 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19d60 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
19d70 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
19d80 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
19d90 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
19da0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
19db0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
19dc0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
19dd0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
19de0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
19df0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
19e00 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
19e10 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
19e20 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
19e30 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
19e40 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
19e50 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
19e60 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
19e70 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
19e80 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
19e90 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
19ea0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
19eb0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
19ec0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
19ed0 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
19ee0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
19ef0 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
19f00 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
19f10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
19f20 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
19f30 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
19f40 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
19f50 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
19f60 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
19f70 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  LL sqlite3_compl
19f80 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
19f90 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
19fa0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
19fb0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
19fc0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
19fd0 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
19fe0 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
19ff0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1a000 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1a010 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1a030 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a040 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1a050 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1a060 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1a070 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1a080 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1a090 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1a0a0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1a0b0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1a0c0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1a0d0 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1a0e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a0f0 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1a100 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1a110 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1a120 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1a130 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1a140 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1a150 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1a160 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1a170 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1a180 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1a190 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1a1a0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1a1b0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a1c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1a1d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1a1e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1a1f0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1a200 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1a210 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1a220 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1a230 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1a240 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1a250 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1a260 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1a270 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1a280 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1a290 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1a2a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1a2b0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1a2c0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1a2d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1a2e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1a2f0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1a300 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1a310 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1a320 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1a330 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1a340 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1a350 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1a360 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1a370 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1a380 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1a390 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1a3a0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1a3b0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1a3c0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1a3d0 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1a3e0 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1a3f0 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1a400 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1a410 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1a420 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1a430 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1a440 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1a450 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1a460 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1a470 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1a480 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1a490 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1a4a0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1a4b0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1a4c0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1a4d0 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1a4e0 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1a4f0 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1a500 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1a510 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1a520 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1a530 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1a540 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1a550 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1a560 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1a570 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1a580 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1a590 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1a5a0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1a5b0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1a5c0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1a5d0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1a5e0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1a5f0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1a600 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1a610 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1a620 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1a630 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1a640 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1a650 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1a660 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1a670 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1a680 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1a690 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1a6a0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1a6b0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1a6c0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1a6d0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1a6e0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1a6f0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1a700 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1a710 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1a720 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1a730 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1a740 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1a750 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1a760 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1a770 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1a780 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1a790 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1a7a0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1a7b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1a7c0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1a7d0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1a7e0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1a7f0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1a800 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1a810 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1a820 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1a830 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1a840 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1a850 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1a860 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1a870 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1a880 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1a890 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1a8a0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1a8b0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1a8c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a8d0 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1a8e0 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1a8f0 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1a900 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1a910 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1a920 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1a930 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1a940 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1a950 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1a960 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1a970 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1a980 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1a990 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1a9a0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1a9b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1a9c0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1a9d0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1a9e0 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1a9f0 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1aa00 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1aa10 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1aa20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1aa30 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1aa40 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1aa50 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1aa60 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1aa70 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1aa80 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1aa90 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1aaa0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1aab0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1aac0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1aad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1aae0 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1aaf0 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1ab00 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1ab10 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
1ab20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
1ab30 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1ab40 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ab50 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1ab60 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1ab70 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1ab80 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1ab90 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1aba0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1abb0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1abc0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1abd0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1abe0 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1abf0 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1ac00 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1ac10 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1ac20 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1ac30 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1ac40 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1ac50 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1ac60 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1ac70 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1ac80 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1ac90 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1aca0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1acb0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1acc0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1acd0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1ace0 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1acf0 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1ad00 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1ad10 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1ad20 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1ad30 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1ad40 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1ad50 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1ad60 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1ad70 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1ad80 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1ad90 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1ada0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1adb0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1adc0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1add0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ade0 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1adf0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1ae00 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1ae10 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1ae20 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1ae30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ae40 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1ae50 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1ae60 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1ae70 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1ae80 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1ae90 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1aea0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1aeb0 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ut].*/.SQLITE_AP
1aec0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1aed0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73  CALL sqlite3_bus
1aee0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1aef0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1af00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1af10 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1af20 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1af30 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1af40 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1af50 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1af60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1af70 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1af80 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1af90 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1afa0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1afb0 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1afc0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1afd0 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1afe0 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1aff0 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1b000 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1b010 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1b020 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1b030 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1b040 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1b050 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1b060 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1b070 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1b080 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1b090 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1b0a0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1b0b0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1b0c0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1b0d0 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1b0e0 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1b0f0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b100 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1b110 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1b120 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1b130 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1b140 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1b150 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1b160 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1b170 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1b180 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1b190 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1b1a0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1b1b0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1b1c0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1b1d0 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1b1e0 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1b1f0 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1b200 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1b210 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b220 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1b230 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1b240 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1b250 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1b260 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1b270 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1b280 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1b290 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1b2a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1b2b0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1b2c0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1b2d0 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1b2e0 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1b2f0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1b300 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1b310 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1b320 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1b330 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1b340 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1b350 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1b360 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1b370 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1b380 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1b390 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1b3a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1b3b0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1b3c0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1b3d0 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1b3e0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1b3f0 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1b400 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1b410 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1b420 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1b430 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1b440 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1b450 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1b460 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1b470 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1b480 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1b490 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1b4a0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1b4b0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1b4c0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1b4d0 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1b4e0 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1b4f0 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1b500 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b510 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1b520 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1b530 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1b540 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1b550 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1b560 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1b570 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1b580 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1b590 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1b5a0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1b5b0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1b5c0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1b5d0 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1b5e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1b5f0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b600 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1b610 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1b620 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1b630 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1b640 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1b650 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1b660 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b670 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1b680 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b690 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1b6a0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b6b0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1b6c0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1b6d0 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1b6e0 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1b6f0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b700 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1b710 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b720 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1b730 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1b740 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1b750 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1b760 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1b770 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1b780 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1b790 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1b7a0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1b7b0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1b7c0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1b7d0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1b7e0 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1b7f0 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1b800 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1b810 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1b820 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1b830 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1b840 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1b850 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1b860 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1b870 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b880 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1b890 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1b8a0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1b8b0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1b8c0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1b8d0 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1b8e0 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1b8f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1b900 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1b910 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1b920 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1b930 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1b940 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1b950 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1b960 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1b970 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1b980 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1b990 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1b9a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1b9b0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1b9c0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1b9d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b9e0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1b9f0 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1ba00 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1ba10 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1ba20 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1ba30 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1ba40 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1ba50 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1ba60 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1ba70 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1ba80 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1ba90 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1baa0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1bab0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1bac0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1bad0 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1bae0 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1baf0 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1bb00 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1bb10 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1bb20 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1bb30 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1bb40 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1bb50 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1bb60 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1bb70 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1bb80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1bb90 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1bba0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1bbb0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1bbc0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1bbd0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1bbe0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1bbf0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1bc00 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1bc10 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1bc20 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1bc30 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1bc40 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1bc50 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1bc60 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1bc70 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1bc80 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1bc90 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1bca0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1bcb0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1bcc0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1bcd0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1bce0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1bcf0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1bd00 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1bd10 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
1bd20 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ALL sqlite3_free
1bd30 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1bd40 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1bd50 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1bd60 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1bd70 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1bd80 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bd90 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1bda0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1bdb0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1bdc0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1bdd0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1bde0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1bdf0 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1be00 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1be10 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1be20 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1be30 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1be40 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1be50 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1be60 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1be70 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1be80 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1be90 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1bea0 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1beb0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1bec0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1bed0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1bee0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1bef0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1bf00 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1bf10 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1bf20 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1bf30 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1bf40 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1bf50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1bf60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1bf70 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1bf80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1bf90 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1bfa0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1bfb0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1bfc0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1bfd0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1bfe0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1bff0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1c000 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1c010 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1c020 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1c030 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1c040 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1c050 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1c060 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1c070 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1c080 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1c090 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1c0a0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1c0b0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1c0c0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1c0d0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1c0e0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1c0f0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1c100 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1c110 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1c120 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1c130 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1c140 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1c150 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1c160 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1c170 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1c180 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1c190 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1c1a0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1c1b0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1c1c0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1c1d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1c1e0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1c1f0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1c200 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1c210 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1c220 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1c230 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1c240 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1c250 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1c260 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1c270 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1c280 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1c290 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1c2a0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1c2b0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1c2c0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1c2d0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1c2e0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1c2f0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1c300 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1c310 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1c320 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1c330 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1c340 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1c350 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1c360 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1c370 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c380 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1c390 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1c3a0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1c3b0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1c3c0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1c3d0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1c3e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1c3f0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1c400 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1c410 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1c420 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1c430 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1c440 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1c450 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1c460 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1c470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1c480 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1c490 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1c4a0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1c4b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c4c0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1c4d0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1c4e0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1c4f0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1c500 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1c510 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1c520 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1c530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1c540 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1c550 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1c560 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1c570 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1c580 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1c590 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1c5a0 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1c5b0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1c5c0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1c5d0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1c5e0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1c5f0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1c600 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1c610 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1c620 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1c630 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1c640 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1c650 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1c660 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1c670 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1c680 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1c690 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1c6a0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1c6b0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1c6c0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1c6d0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1c6e0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1c6f0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1c700 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1c710 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1c720 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1c730 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1c740 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1c750 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1c760 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1c770 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1c780 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c790 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1c7a0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1c7b0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1c7c0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1c7d0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c7e0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c7f0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1c800 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1c810 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1c820 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1c830 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1c840 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1c850 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1c860 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1c870 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1c880 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c890 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1c8a0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1c8b0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1c8c0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1c8d0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1c8e0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1c8f0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1c900 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c910 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c920 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1c930 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1c940 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1c950 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1c960 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1c970 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1c980 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1c990 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1c9a0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1c9b0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1c9c0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1c9d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c9e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1c9f0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1ca00 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1ca10 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1ca20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1ca30 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1ca40 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1ca50 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1ca60 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1ca70 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1ca80 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1ca90 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1caa0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1cab0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1cac0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1cad0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1cae0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1caf0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1cb00 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1cb10 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1cb20 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1cb30 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1cb40 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1cb50 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1cb60 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1cb70 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1cb80 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1cb90 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1cba0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1cbb0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1cbc0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1cbd0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1cbe0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1cbf0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1cc00 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1cc10 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1cc20 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1cc30 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1cc40 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1cc50 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1cc60 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1cc70 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1cc80 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1cc90 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1cca0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1ccb0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1ccc0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1ccd0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1cce0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1ccf0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1cd00 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1cd10 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1cd20 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1cd30 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1cd40 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1cd50 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1cd60 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1cd70 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1cd80 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1cd90 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1cda0 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1cdb0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1cdc0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1cdd0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1cde0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1cdf0 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1ce00 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1ce10 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1ce20 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1ce30 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1ce40 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1ce50 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1ce60 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1ce70 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1ce80 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1ce90 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1cea0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1ceb0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1cec0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1ced0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1cee0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1cef0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1cf00 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1cf10 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1cf20 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1cf30 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1cf40 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1cf50 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
1cf60 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1cf70 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
1cf80 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1cf90 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1cfa0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1cfb0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1cfc0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1cfd0 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c  ar *SQLITE_CDECL
1cfe0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1cff0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1d000 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1d010 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1d020 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1d030 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1d040 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1d050 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1d060 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d070 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1d080 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1d090 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1d0a0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1d0b0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1d0c0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1d0d0 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1d0e0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d0f0 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1d100 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1d110 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1d120 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1d130 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1d140 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1d150 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1d160 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1d170 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1d180 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1d190 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1d1a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d1b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1d1c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1d1d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1d1e0 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1d1f0 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1d200 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1d210 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1d220 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1d230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1d240 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1d250 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1d260 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1d270 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1d280 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1d290 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1d2a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d2b0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1d2c0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1d2d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1d2e0 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1d2f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1d300 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1d310 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
1d320 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
1d330 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d340 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
1d350 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
1d360 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
1d370 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1d380 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
1d390 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
1d3a0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1d3b0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1d3c0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1d3d0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1d3e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d3f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1d400 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1d410 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1d420 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1d430 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1d440 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1d450 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1d460 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1d470 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1d480 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1d490 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1d4a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1d4b0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1d4c0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1d4d0 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1d4e0 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1d4f0 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1d500 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1d510 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1d520 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1d530 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1d540 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1d550 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1d560 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1d570 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1d580 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d590 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1d5a0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1d5b0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1d5c0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1d5d0 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1d5e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1d5f0 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1d600 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1d610 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1d620 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1d630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1d650 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1d660 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1d670 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1d680 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
1d690 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1d6a0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
1d6b0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
1d6c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1d6d0 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
1d6e0 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1d6f0 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1d700 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1d710 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1d720 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
1d730 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
1d740 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1d750 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
1d760 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1d770 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1d780 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1d790 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1d7a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1d7b0 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
1d7c0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1d7d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d7e0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1d7f0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1d800 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1d810 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1d820 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
1d830 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
1d840 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1d850 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1d860 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1d870 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1d880 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1d890 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1d8a0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1d8b0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1d8c0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1d8d0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1d8e0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
1d8f0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1d900 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1d910 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1d920 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1d930 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
1d940 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
1d950 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
1d960 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
1d970 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1d980 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d990 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
1d9a0 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
1d9b0 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
1d9c0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
1d9d0 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
1d9e0 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1d9f0 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1da00 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
1da10 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1da20 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
1da30 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1da40 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
1da50 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1da60 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
1da70 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1da80 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1da90 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
1daa0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
1dab0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1dac0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1dad0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
1dae0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1daf0 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
1db00 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1db10 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1db20 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
1db30 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1db40 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
1db50 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
1db60 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
1db70 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
1db80 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1db90 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1dba0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
1dbb0 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
1dbc0 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
1dbd0 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
1dbe0 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
1dbf0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
1dc00 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
1dc10 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
1dc20 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
1dc30 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
1dc40 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
1dc50 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
1dc60 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
1dc70 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
1dc80 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
1dc90 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
1dca0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1dcb0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1dcc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
1dcd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dce0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1dcf0 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
1dd00 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1dd10 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1dd20 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1dd30 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1dd40 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1dd50 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1dd60 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1dd70 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1dd80 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1dd90 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1dda0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1ddb0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1ddc0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1ddd0 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1dde0 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1ddf0 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1de00 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1de10 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1de20 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1de30 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1de40 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1de50 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1de60 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1de70 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1de80 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1de90 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1dea0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1deb0 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1dec0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1ded0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1dee0 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1def0 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1df00 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1df10 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1df20 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1df30 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1df40 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1df50 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1df60 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1df70 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1df80 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1df90 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1dfa0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1dfb0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1dfc0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1dfd0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1dfe0 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1dff0 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1e000 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1e010 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1e020 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1e030 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1e040 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1e050 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1e060 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1e070 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1e080 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1e090 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e0a0 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1e0b0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1e0c0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1e0d0 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1e0e0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1e0f0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1e100 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1e110 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1e120 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1e130 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1e140 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1e150 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1e160 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1e170 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1e180 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1e190 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1e1a0 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1e1b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1e1c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1e1d0 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51  ealloc()]..*/.SQ
1e1e0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
1e1f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1e200 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1e210 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1e220 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1e230 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
1e240 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1e250 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
1e260 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
1e270 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61  CALL sqlite3_rea
1e280 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1e290 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1e2a0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1e2b0 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  L sqlite3_reallo
1e2c0 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1e2d0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
1e2e0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
1e2f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1e300 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1e310 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1e320 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45  e3_uint64 SQLITE
1e330 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1e340 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1e350 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e360 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1e370 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1e380 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1e390 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1e3a0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1e3b0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1e3c0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1e3d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1e3e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e3f0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1e400 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1e410 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1e420 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1e430 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1e440 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1e450 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1e460 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1e470 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1e480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1e490 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1e4a0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1e4b0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1e4c0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1e4d0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1e4e0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1e4f0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1e500 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1e510 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1e520 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e530 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1e540 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1e550 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1e560 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1e570 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1e580 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1e590 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1e5a0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e5b0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1e5c0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1e5d0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1e5e0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1e5f0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1e600 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1e610 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1e620 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1e630 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1e640 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1e650 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1e660 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1e670 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1e680 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1e690 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1e6a0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1e6b0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1e6c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e6d0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1e6e0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1e6f0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1e700 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e710 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1e720 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1e730 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1e740 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1e750 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1e760 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1e770 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1e780 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
1e790 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1e7a0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
1e7b0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  LL sqlite3_memor
1e7c0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51  y_used(void);.SQ
1e7d0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1e7e0 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
1e7f0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65  DCALL sqlite3_me
1e800 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
1e810 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
1e820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1e830 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
1e840 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
1e850 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
1e860 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
1e870 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
1e880 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
1e890 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
1e8a0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
1e8b0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
1e8c0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
1e8d0 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
1e8e0 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
1e8f0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
1e900 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
1e910 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
1e920 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
1e930 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
1e940 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
1e950 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
1e960 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
1e970 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
1e980 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
1e990 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
1e9a0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
1e9b0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
1e9c0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
1e9d0 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
1e9e0 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
1e9f0 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
1ea00 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
1ea10 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
1ea20 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
1ea30 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1ea40 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
1ea50 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
1ea60 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
1ea70 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
1ea80 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
1ea90 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
1eaa0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
1eab0 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
1eac0 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
1ead0 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
1eae0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
1eaf0 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
1eb00 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
1eb10 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1eb20 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1eb30 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
1eb40 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
1eb50 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
1eb60 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
1eb70 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
1eb80 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
1eb90 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1eba0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1ebb0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1ebc0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1ebd0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1ebe0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1ebf0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
1ec00 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
1ec10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1ec20 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
1ec30 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
1ec40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ec50 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
1ec60 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
1ec70 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
1ec80 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ec90 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1eca0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1ecb0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ecc0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1ecd0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1ece0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1ecf0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1ed00 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1ed10 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1ed20 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1ed30 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1ed40 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1ed50 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1ed60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1ed70 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1ed80 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1ed90 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1eda0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1edb0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1edc0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1edd0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1ede0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1edf0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1ee00 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1ee10 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1ee20 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1ee30 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1ee40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ee50 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1ee60 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1ee70 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1ee80 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1ee90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1eea0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1eeb0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1eec0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1eed0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1eee0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1eef0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1ef00 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1ef10 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1ef20 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1ef30 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1ef40 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1ef50 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1ef60 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1ef70 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1ef80 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1ef90 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1efa0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1efb0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1efc0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1efd0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1efe0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1eff0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1f000 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1f010 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1f020 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1f030 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1f040 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1f050 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1f060 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1f070 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1f080 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1f090 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1f0a0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1f0b0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1f0c0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1f0d0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1f0e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f0f0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1f100 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1f110 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f120 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1f130 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1f140 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1f150 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1f160 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1f170 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1f180 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1f190 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1f1a0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1f1b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1f1c0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f1d0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1f1e0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1f1f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1f200 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1f210 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1f220 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1f230 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1f240 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1f250 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1f260 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1f270 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1f280 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1f290 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1f2a0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1f2b0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1f2c0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1f2d0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1f2e0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1f2f0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1f300 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1f310 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1f320 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1f330 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1f340 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1f350 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1f360 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1f370 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1f380 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1f390 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1f3a0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1f3b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1f3c0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1f3d0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1f3e0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1f3f0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1f400 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1f410 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1f420 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1f430 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1f440 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1f450 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1f460 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1f470 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1f480 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1f490 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1f4a0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1f4b0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1f4c0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1f4d0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1f4e0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1f4f0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1f500 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1f510 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1f520 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1f530 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1f540 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1f550 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1f560 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1f570 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1f580 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1f590 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1f5a0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1f5b0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1f5c0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1f5d0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1f5e0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1f5f0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1f600 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1f610 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1f620 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1f630 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1f640 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1f650 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1f660 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1f670 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1f680 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1f690 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1f6a0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1f6b0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1f6c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1f6d0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1f6e0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1f6f0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1f700 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1f710 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1f720 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1f730 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1f740 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1f750 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1f760 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1f770 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1f780 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1f790 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1f7a0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1f7b0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1f7c0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1f7d0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1f7e0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1f7f0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1f800 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1f810 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1f820 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1f830 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1f840 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1f850 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1f860 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1f870 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1f880 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1f890 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1f8a0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1f8b0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1f8c0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1f8d0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1f8e0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1f8f0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1f900 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1f910 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1f920 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1f930 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1f940 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1f950 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1f960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1f970 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1f980 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1f990 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1f9a0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1f9b0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1f9c0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1f9d0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1f9e0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1f9f0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1fa00 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1fa10 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1fa20 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1fa30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fa40 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1fa50 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1fa60 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1fa70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fa80 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1fa90 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1faa0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1fab0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1fac0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1fad0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1fae0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1faf0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1fb00 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1fb10 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1fb20 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1fb30 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1fb40 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1fb50 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1fb60 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1fb70 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1fb80 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1fb90 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1fba0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1fbb0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1fbc0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1fbd0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1fbe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1fbf0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1fc00 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1fc10 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1fc20 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1fc30 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1fc40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1fc50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1fc60 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1fc70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1fc80 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1fc90 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1fca0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1fcb0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1fcc0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1fcd0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1fce0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1fcf0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1fd00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1fd10 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1fd20 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1fd30 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1fd40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1fd50 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1fd60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1fd70 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1fd80 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1fd90 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1fda0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1fdb0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1fdc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1fdd0 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1fde0 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1fdf0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1fe00 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1fe10 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1fe20 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1fe30 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1fe40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1fe50 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1fe60 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1fe70 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1fe80 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1fe90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fea0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1feb0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1fec0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1fed0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1fee0 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1fef0 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1ff00 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1ff10 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1ff20 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1ff30 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1ff40 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ff50 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1ff60 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1ff70 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1ff80 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1ff90 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1ffa0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1ffb0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1ffc0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
1ffd0 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
1ffe0 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
1fff0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
20000 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
20010 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
20020 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
20030 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
20040 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
20050 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
20060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20070 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
20080 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
20090 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
200a0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
200b0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
200c0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
200d0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
200e0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
200f0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
20100 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
20110 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
20120 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
20130 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
20140 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
20150 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
20160 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
20170 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20180 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20190 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
201a0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
201b0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
201c0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
201d0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
201e0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
201f0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
20200 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
20210 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
20220 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
20230 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
20240 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
20250 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
20260 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
20270 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
20280 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
20290 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
202a0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
202b0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
202c0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
202d0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
202e0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
202f0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
20300 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
20310 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
20320 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
20330 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
20340 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20350 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
20360 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
20370 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
20380 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
20390 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
203a0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
203b0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
203c0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
203d0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
203e0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
203f0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
20400 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
20410 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
20420 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
20430 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
20440 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
20450 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
20460 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
20470 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
20480 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20490 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
204a0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
204b0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
204c0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
204d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
204e0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
204f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
20500 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20510 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20520 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
20530 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
20540 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20550 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20560 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20570 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
20580 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
20590 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
205a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
205b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
205c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
205d0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
205e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
205f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20610 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20620 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
20630 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
20640 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20660 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
20670 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
20680 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
20690 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
206a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
206b0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
206c0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
206d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
206e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
206f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20700 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
20710 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
20720 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
20730 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20750 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
20760 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
20770 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
20780 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
207a0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
207b0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
207c0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
207d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
207e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
207f0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
20800 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
20810 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20820 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20830 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20840 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
20850 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
20860 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
20870 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20880 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20890 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
208a0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
208b0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
208c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
208d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
208e0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
208f0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
20900 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
20910 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
20920 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20930 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
20940 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
20950 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
20960 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20970 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
20980 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
20990 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
209a0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
209b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
209c0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
209d0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
209e0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
209f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20a00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20a10 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
20a20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
20a30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
20a40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
20a50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20a60 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
20a70 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
20a80 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
20a90 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
20aa0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
20ab0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
20ac0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
20ad0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20ae0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
20af0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20b00 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
20b10 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
20b20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20b30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20b40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20b50 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
20b60 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
20b70 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
20b80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20b90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20ba0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
20bb0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
20bc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
20bd0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
20be0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20bf0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
20c00 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
20c10 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
20c20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
20c30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20c40 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
20c50 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
20c60 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
20c70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20c80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
20c90 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
20ca0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
20cb0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
20cc0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
20cd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
20ce0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
20cf0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
20d00 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
20d10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
20d20 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
20d30 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
20d40 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
20d50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20d60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20d70 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20d80 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
20d90 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
20da0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
20db0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20dc0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
20dd0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
20de0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
20df0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20e00 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20e10 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
20e20 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
20e30 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
20e40 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
20e50 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
20e60 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
20e70 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
20e80 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
20e90 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
20ea0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
20eb0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
20ec0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
20ed0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
20ee0 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
20ef0 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
20f00 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
20f10 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
20f20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20f30 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
20f40 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
20f50 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
20f60 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
20f70 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
20f80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
20f90 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
20fa0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
20fb0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
20fc0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
20fd0 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
20fe0 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
20ff0 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
21000 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
21010 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
21020 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
21030 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
21040 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
21050 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
21060 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
21070 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
21080 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
21090 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
210a0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
210b0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
210c0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
210d0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
210e0 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
210f0 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
21100 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
21110 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
21120 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
21130 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
21140 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
21150 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
21160 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
21170 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
21180 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
21190 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
211a0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
211b0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
211c0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
211d0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
211e0 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
211f0 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
21200 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
21210 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
21220 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
21230 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
21240 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
21250 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
21260 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
21270 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
21280 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
21290 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
212a0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
212b0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
212c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
212d0 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
212e0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
212f0 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
21300 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
21310 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
21320 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
21330 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
21340 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
21350 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
21360 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
21370 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
21380 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
21390 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
213a0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
213b0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
213c0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
213d0 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
213e0 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
213f0 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
21400 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
21410 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
21420 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
21430 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
21440 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
21450 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
21460 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
21470 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
21480 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
21490 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
214a0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
214b0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
214c0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
214d0 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
214e0 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
214f0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
21500 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
21510 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
21520 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
21530 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
21540 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
21550 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
21560 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
21570 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
21580 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51  IMENTAL void *SQ
21590 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
215a0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
215b0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
215c0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
215d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
215e0 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
215f0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
21600 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
21610 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
21620 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
21630 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
21640 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
21650 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
21660 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
21670 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
21680 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
21690 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
216a0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
216b0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
216c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
216d0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
216e0 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
216f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
21700 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
21710 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
21720 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
21730 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
21740 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
21750 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
21760 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
21770 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
21780 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
21790 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
217a0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
217b0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
217c0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
217d0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
217e0 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
217f0 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
21800 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
21810 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
21820 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
21830 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
21840 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
21850 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
21860 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
21870 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
21880 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
21890 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
218a0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
218b0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
218c0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
218d0 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
218e0 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
218f0 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
21900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
21910 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
21920 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
21930 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
21940 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
21950 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
21960 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
21970 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
21980 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
21990 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
219a0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
219b0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
219c0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
219d0 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
219e0 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
219f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
21a00 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
21a10 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
21a20 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
21a30 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
21a40 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
21a50 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
21a60 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
21a70 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
21a80 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
21a90 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
21aa0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
21ab0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
21ac0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
21ad0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
21ae0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
21af0 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
21b00 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
21b10 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
21b20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
21b30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
21b40 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
21b50 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
21b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
21b70 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
21b80 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
21b90 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
21ba0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
21bb0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
21bc0 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  L sqlite3_progre
21bd0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
21be0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
21bf0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
21c00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21c10 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
21c20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
21c30 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
21c40 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
21c50 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
21c60 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
21c70 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
21c80 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
21c90 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
21ca0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
21cb0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21cc0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
21cd0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
21ce0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
21cf0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
21d00 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
21d10 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
21d20 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
21d30 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
21d40 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
21d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21d60 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
21d70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
21d80 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
21d90 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
21da0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
21db0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
21dc0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
21dd0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
21de0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
21df0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
21e00 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
21e10 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
21e20 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
21e30 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
21e40 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
21e50 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
21e60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
21e70 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
21e80 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
21e90 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
21ea0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
21eb0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
21ec0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21ed0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
21ee0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
21ef0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
21f00 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
21f10 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
21f20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
21f30 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
21f40 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
21f50 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
21f60 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
21f70 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
21f80 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
21f90 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
21fa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
21fb0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
21fc0 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
21fd0 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
21fe0 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
21ff0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
22000 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
22010 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
22020 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
22030 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
22040 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
22050 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
22060 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
22070 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
22080 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
22090 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
220a0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
220b0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
220c0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
220d0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
220e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
220f0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
22100 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
22110 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
22120 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
22130 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
22140 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
22150 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
22160 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
22170 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
22180 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
22190 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
221a0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
221b0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
221c0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
221d0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
221e0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
221f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
22200 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
22210 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
22220 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
22230 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
22240 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
22250 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
22260 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
22270 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
22280 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
22290 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
222a0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
222b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
222c0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
222d0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
222e0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
222f0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
22300 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
22310 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
22320 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22330 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
22340 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
22350 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
22360 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
22370 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
22380 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
22390 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
223a0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
223b0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
223c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
223d0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
223e0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
223f0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
22400 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
22410 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
22420 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
22430 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
22440 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
22450 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
22460 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
22470 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
22480 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
22490 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
224a0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
224b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
224c0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
224d0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
224e0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
224f0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
22500 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22510 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22520 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
22530 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
22540 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
22550 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
22560 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
22570 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
22580 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
22590 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
225a0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
225b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
225c0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
225d0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
225e0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
225f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22600 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
22610 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
22620 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
22630 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
22640 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
22650 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
22660 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
22670 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
22680 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
22690 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
226a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
226b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
226c0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
226d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
226e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
226f0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
22700 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
22710 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
22720 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
22730 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
22740 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
22750 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
22760 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22770 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
22780 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
22790 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
227a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
227b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
227c0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
227d0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
227e0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
227f0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
22800 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
22810 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
22820 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
22830 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
22840 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
22850 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
22860 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
22870 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
22880 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
22890 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
228a0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
228b0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
228c0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
228d0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
228e0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
228f0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
22900 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
22910 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
22920 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
22930 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
22940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22950 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
22960 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
22970 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
22980 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
22990 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
229a0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
229b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
229c0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
229d0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
229e0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
229f0 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
22a00 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
22a10 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
22a20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
22a30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22a40 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
22a50 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
22a60 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
22a70 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
22a80 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
22a90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
22aa0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
22ab0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22ac0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
22ad0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
22ae0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
22af0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
22b00 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
22b10 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
22b20 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
22b30 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
22b40 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
22b50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22b60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
22b70 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
22b80 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
22b90 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
22ba0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
22bb0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
22bc0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
22bd0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
22be0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
22bf0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
22c00 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
22c10 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
22c20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
22c30 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
22c40 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
22c50 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
22c60 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
22c70 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
22c80 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
22c90 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
22ca0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22cb0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
22cc0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
22cd0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
22ce0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
22cf0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
22d00 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
22d10 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
22d20 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22d30 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
22d40 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
22d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
22d60 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
22d70 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
22d80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
22d90 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
22da0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
22db0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
22dc0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
22dd0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
22de0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
22df0 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
22e00 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
22e10 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
22e20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22e30 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
22e40 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
22e50 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22e60 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
22e70 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
22e80 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
22e90 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
22ea0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
22eb0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
22ec0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
22ed0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
22ee0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
22ef0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
22f00 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
22f10 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
22f20 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
22f30 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
22f40 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
22f50 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
22f60 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
22f70 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
22f80 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22f90 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
22fa0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
22fb0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
22fc0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
22fd0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
22fe0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
22ff0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
23000 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
23010 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
23020 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
23030 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
23040 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
23050 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
23060 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
23070 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
23080 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
23090 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
230a0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
230b0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
230c0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
230d0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
230e0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
230f0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
23100 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
23110 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
23120 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23130 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
23140 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
23150 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
23160 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
23170 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
23180 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
23190 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
231a0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
231b0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
231c0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
231d0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
231e0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
231f0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
23200 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
23210 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
23220 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
23230 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
23240 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
23250 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
23260 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
23270 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
23280 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
23290 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
232a0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
232b0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
232c0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
232d0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
232e0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
232f0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
23300 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
23310 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
23320 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
23330 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
23340 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
23350 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
23360 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
23370 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
23380 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
23390 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
233a0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
233b0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
233c0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
233d0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
233e0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
233f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
23400 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
23410 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
23420 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
23430 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
23440 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
23450 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
23460 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
23470 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
23480 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
23490 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
234a0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
234b0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
234c0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
234d0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
234e0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
234f0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
23500 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
23510 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23520 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
23530 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
23540 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
23550 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
23560 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
23570 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
23580 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
23590 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
235a0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
235b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
235c0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
235d0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
235e0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
235f0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
23600 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
23610 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
23620 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
23630 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
23640 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
23650 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
23660 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
23670 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
23680 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
23690 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
236a0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
236b0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
236c0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
236d0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
236e0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
236f0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
23700 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
23710 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
23720 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
23730 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
23740 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23750 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
23760 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
23770 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
23780 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
23790 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
237a0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
237b0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
237c0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
237d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
237e0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
237f0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
23800 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
23810 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23820 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
23830 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
23840 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
23850 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
23860 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
23870 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
23880 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
23890 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
238a0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
238b0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
238c0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
238d0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
238e0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
238f0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
23900 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
23910 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
23920 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
23930 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
23940 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
23950 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
23960 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
23970 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
23980 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
23990 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
239a0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
239b0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
239c0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
239d0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
239e0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
239f0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
23a00 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
23a10 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
23a20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
23a30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
23a40 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
23a50 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
23a60 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
23a70 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
23a80 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
23a90 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
23aa0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
23ab0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
23ac0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
23ad0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
23ae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
23af0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
23b00 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
23b10 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
23b20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
23b30 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
23b40 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
23b50 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
23b60 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
23b70 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23b80 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
23b90 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
23ba0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
23bb0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23bc0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
23bd0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
23be0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
23bf0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
23c00 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
23c10 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
23c20 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
23c30 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
23c40 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
23c50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
23c60 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
23c70 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
23c80 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
23c90 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
23ca0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
23cb0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
23cc0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
23cd0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
23ce0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
23cf0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
23d00 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
23d10 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
23d20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
23d30 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
23d40 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
23d50 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
23d60 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
23d70 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
23d80 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
23d90 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
23da0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
23db0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
23dc0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
23dd0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
23de0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
23df0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
23e00 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
23e10 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
23e20 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
23e30 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
23e40 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
23e50 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
23e60 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
23e70 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
23e80 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
23e90 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
23ea0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
23eb0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
23ec0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
23ed0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
23ee0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
23ef0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
23f00 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
23f10 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23f20 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
23f30 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
23f40 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
23f50 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
23f60 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
23f70 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
23f80 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
23f90 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
23fa0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
23fb0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
23fc0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
23fd0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
23fe0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
23ff0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
24000 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
24010 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24020 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
24030 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
24040 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
24050 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
24060 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
24070 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
24080 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
24090 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
240a0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
240b0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
240c0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
240d0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
240e0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
240f0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
24100 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
24110 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
24120 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
24130 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
24140 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
24150 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
24160 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
24170 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
24180 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
24190 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
241a0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
241b0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
241c0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
241d0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
241e0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
241f0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
24200 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
24210 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
24220 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
24230 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
24240 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
24250 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
24260 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
24270 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
24280 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
24290 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
242a0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
242b0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
242c0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
242d0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
242e0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
242f0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
24300 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
24310 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
24320 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
24330 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
24340 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
24350 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
24360 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
24370 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
24380 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
24390 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
243a0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
243b0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
243c0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
243d0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
243e0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
243f0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
24400 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
24410 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
24420 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
24430 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
24440 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
24450 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
24460 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
24470 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
24480 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
24490 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
244a0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
244b0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
244c0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
244d0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
244e0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
244f0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
24500 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
24510 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
24520 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
24530 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
24540 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
24550 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
24560 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
24570 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
24580 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
24590 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
245a0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
245b0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
245c0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
245d0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
245e0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
245f0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
24600 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
24610 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
24620 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
24630 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
24640 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
24650 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
24660 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
24670 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
24680 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24690 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
246a0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
246b0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
246c0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
246d0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
246e0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
246f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24700 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
24710 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
24720 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
24730 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24740 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
24750 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
24760 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
24770 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
24780 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
24790 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
247a0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
247b0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
247c0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
247d0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
247e0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
247f0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
24800 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
24810 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
24820 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
24830 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
24840 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24850 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
24860 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
24870 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
24880 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
24890 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
248a0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
248b0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
248c0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
248d0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
248e0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
248f0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
24900 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
24910 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
24920 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
24930 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
24940 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
24950 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
24960 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
24970 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
24980 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
24990 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
249a0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
249b0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
249c0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
249d0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
249e0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
249f0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
24a00 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
24a10 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
24a20 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
24a30 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
24a40 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
24a50 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
24a60 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
24a70 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
24a80 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
24a90 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
24aa0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
24ab0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24ac0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24ad0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
24ae0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
24af0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
24b00 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
24b10 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
24b20 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
24b30 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
24b40 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
24b50 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
24b60 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
24b70 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
24b80 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
24b90 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
24ba0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
24bb0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
24bc0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
24bd0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
24be0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
24bf0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
24c00 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
24c10 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
24c20 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
24c30 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
24c40 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
24c50 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
24c60 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
24c70 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
24c80 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24c90 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
24ca0 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
24cb0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
24cc0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
24cd0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
24ce0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
24cf0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24d00 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
24d10 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
24d20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
24d30 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
24d40 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
24d50 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
24d60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
24d70 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
24d80 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24d90 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
24da0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
24db0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
24dc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
24dd0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24de0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
24df0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
24e00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70  DCALL sqlite3_op
24e10 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
24e20 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
24e30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
24e40 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
24e50 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
24e60 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
24e70 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
24e80 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
24e90 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
24ea0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
24eb0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
24ec0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
24ed0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
24ee0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
24ef0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
24f00 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
24f10 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
24f20 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
24f30 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
24f40 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
24f50 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
24f60 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
24f70 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
24f80 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
24f90 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
24fa0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
24fb0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
24fc0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
24fd0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
24fe0 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
24ff0 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
25000 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
25010 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
25020 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
25030 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
25040 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
25050 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
25060 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
25070 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
25080 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
25090 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
250a0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
250b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
250c0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
250d0 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
250e0 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
250f0 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
25100 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
25110 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25120 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
25130 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
25140 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
25150 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
25160 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
25170 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
25180 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
25190 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
251a0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
251b0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
251c0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
251d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
251e0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
251f0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
25200 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
25210 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
25220 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
25230 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
25240 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
25250 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
25260 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
25270 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
25280 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
25290 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
252a0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
252b0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
252c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
252d0 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
252e0 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
252f0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
25300 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
25310 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
25320 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
25330 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
25340 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
25350 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
25360 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
25370 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
25380 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25390 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
253a0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
253b0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
253c0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
253d0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
253e0 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
253f0 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
25400 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
25410 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
25420 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
25430 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
25440 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
25450 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
25460 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
25470 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
25480 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
25490 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
254a0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
254b0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
254c0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
254d0 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
254e0 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
254f0 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
25500 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
25510 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
25520 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
25530 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
25540 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
25550 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
25560 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
25570 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
25580 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
25590 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
255a0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
255b0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
255c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
255d0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
255e0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
255f0 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
25600 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
25610 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
25620 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
25630 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
25640 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
25650 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
25660 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
25670 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
25680 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
25690 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
256a0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
256b0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
256c0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
256d0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
256e0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
256f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
25700 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
25710 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
25720 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
25730 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
25740 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
25750 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
25760 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
25770 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
25780 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
25790 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
257a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
257b0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
257c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
257d0 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
257e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
257f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
25800 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
25810 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
25820 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
25830 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
25840 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
25850 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
25860 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
25870 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
25880 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
25890 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
258a0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
258b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
258c0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
258d0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
258e0 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
258f0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
25900 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
25910 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
25920 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
25930 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
25940 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
25950 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
25960 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
25970 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
25980 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
25990 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
259a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
259b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
259c0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
259d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
259e0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
259f0 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
25a00 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
25a10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
25a20 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
25a30 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
25a40 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
25a50 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
25a60 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
25a70 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
25a80 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
25a90 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
25aa0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
25ab0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
25ac0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
25ad0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
25ae0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25af0 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25b00 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
25b10 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
25b20 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
25b30 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
25b40 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
25b50 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
25b60 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
25b70 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
25b80 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
25b90 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
25ba0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
25bb0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
25bc0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
25bd0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
25be0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
25bf0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
25c00 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
25c10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25c20 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
25c30 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
25c40 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
25c50 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
25c60 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
25c70 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
25c80 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
25c90 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
25ca0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
25cb0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
25cc0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
25cd0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
25ce0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
25cf0 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25d00 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
25d10 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
25d20 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
25d30 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
25d40 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
25d50 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
25d60 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
25d70 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
25d80 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
25d90 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
25da0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
25db0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
25dc0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
25dd0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
25de0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
25df0 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
25e00 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
25e10 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
25e20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
25e30 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
25e40 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
25e50 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
25e60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25e70 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
25e80 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
25e90 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
25ea0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
25eb0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
25ec0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
25ed0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
25ee0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25ef0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
25f00 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
25f10 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
25f20 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
25f30 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
25f40 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
25f50 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
25f60 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
25f70 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
25f80 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
25f90 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
25fa0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
25fb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
25fc0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
25fd0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
25fe0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
25ff0 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
26000 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
26010 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
26020 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72  DCALL sqlite3_er
26030 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
26040 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
26050 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
26060 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  L sqlite3_extend
26070 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
26080 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
26090 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
260a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
260b0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
260c0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
260d0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
260e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
260f0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
26100 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
26110 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
26120 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
26130 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
26140 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26150 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
26160 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26170 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26190 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
261a0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
261b0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
261c0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
261d0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
261e0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
261f0 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
26200 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
26210 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
26220 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
26230 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
26240 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
26250 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
26260 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
26270 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
26280 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
26290 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
262a0 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
262b0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
262c0 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
262d0 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
262e0 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
262f0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
26300 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
26310 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
26320 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
26330 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
26340 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
26350 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
26360 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
26370 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
26380 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
26390 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
263a0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
263b0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
263c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
263d0 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
263e0 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
263f0 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
26400 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
26410 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
26420 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
26430 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
26440 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26450 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
26460 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
26470 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
26480 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
26490 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
264a0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
264b0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
264c0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
264d0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
264e0 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
264f0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
26500 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
26510 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
26520 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
26530 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
26540 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
26550 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
26560 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
26570 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
26580 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
26590 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
265a0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
265b0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
265c0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
265d0 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
265e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
265f0 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
26600 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
26610 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
26620 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
26630 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
26640 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
26650 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
26660 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
26670 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
26680 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
26690 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
266a0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
266b0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
266c0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
266d0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
266e0 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
266f0 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
26700 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
26710 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
26720 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
26730 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
26740 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
26750 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
26760 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
26770 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
26780 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
26790 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
267a0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
267b0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
267c0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
267d0 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
267e0 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
267f0 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
26800 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
26810 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
26820 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
26830 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
26840 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
26850 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
26860 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
26870 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
26880 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
26890 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
268a0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
268b0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
268c0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
268d0 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
268e0 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
268f0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
26900 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26910 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
26920 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
26930 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
26940 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
26950 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
26960 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
26970 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
26980 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
26990 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
269a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
269b0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
269c0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
269d0 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
269e0 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
269f0 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
26a00 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
26a10 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
26a20 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
26a30 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
26a40 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
26a50 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
26a60 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
26a70 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
26a80 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
26a90 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
26aa0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
26ab0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
26ac0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
26ad0 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
26ae0 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
26af0 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
26b00 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
26b10 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
26b20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
26b30 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
26b40 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
26b50 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
26b60 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
26b70 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
26b80 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
26b90 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
26ba0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
26bb0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
26bc0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
26bd0 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
26be0 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
26bf0 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
26c00 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
26c10 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
26c20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
26c30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
26c40 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
26c50 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
26c60 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
26c70 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
26c80 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
26c90 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
26ca0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
26cb0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
26cc0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
26cd0 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
26ce0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
26cf0 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
26d00 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
26d10 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c  releases..*/.SQL
26d20 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
26d30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
26d40 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
26d50 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
26d60 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
26d70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
26d80 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
26d90 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
26da0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
26db0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
26dc0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
26dd0 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
26de0 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
26df0 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
26e00 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
26e10 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
26e20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
26e30 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
26e40 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
26e50 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
26e60 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
26e70 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
26e80 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
26e90 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
26ea0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
26eb0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
26ec0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
26ed0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
26ee0 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
26ef0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
26f00 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26f10 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
26f20 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
26f30 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
26f40 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
26f50 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
26f60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26f70 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
26f80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
26f90 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
26fa0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
26fb0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
26fc0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
26fd0 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
26fe0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26ff0 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
27000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
27010 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
27020 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27030 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
27040 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
27050 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
27060 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
27070 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
27080 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
27090 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
270a0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
270b0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
270c0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
270d0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
270e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
270f0 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
27100 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
27110 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
27120 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
27130 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
27140 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
27150 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
27160 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27170 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
27180 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
27190 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
271a0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
271b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
271c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
271d0 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
271e0 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
271f0 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
27200 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27210 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
27220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
27230 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
27240 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27250 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
27260 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
27270 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
27280 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
27290 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
272a0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
272b0 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
272c0 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
272d0 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
272e0 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
272f0 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
27300 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
27310 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
27320 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
27330 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
27340 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
27350 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
27360 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27370 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
27380 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
27390 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
273a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
273b0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
273c0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
273d0 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
273e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
273f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
27400 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
27410 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
27420 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
27430 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
27440 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
27450 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27460 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
27470 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
27480 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
27490 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
274a0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
274b0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
274c0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
274d0 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
274e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
274f0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
27500 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
27510 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27520 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
27530 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27540 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
27550 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
27560 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
27570 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
27580 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
27590 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
275a0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
275b0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
275c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
275d0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
275e0 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
275f0 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
27600 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27610 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
27620 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27630 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
27640 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
27650 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27660 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
27670 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
27680 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
27690 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
276a0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
276b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
276c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
276d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
276e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
276f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
27700 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
27710 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
27720 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
27730 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
27740 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
27750 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
27760 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
27770 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27780 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
27790 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
277a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
277b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
277c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
277d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
277e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
277f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
27800 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
27810 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
27820 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27830 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
27840 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
27850 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27860 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27870 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
27880 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27890 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
278a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
278b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
278c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
278d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
278e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
278f0 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
27900 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
27910 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27920 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
27930 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
27940 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
27950 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
27960 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
27970 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
27980 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
27990 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
279a0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
279b0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
279c0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
279d0 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
279e0 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
279f0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
27a00 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
27a10 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
27a20 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
27a30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
27a40 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
27a50 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
27a60 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
27a70 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
27a80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
27a90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
27aa0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
27ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27ac0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
27ad0 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
27ae0 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
27af0 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
27b00 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
27b10 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
27b20 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
27b30 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
27b40 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
27b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
27b60 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
27b70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
27b80 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
27b90 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
27ba0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
27bb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27bc0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
27bd0 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
27be0 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
27bf0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
27c00 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
27c10 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
27c20 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
27c30 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
27c40 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
27c50 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
27c60 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
27c70 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
27c80 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
27c90 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
27ca0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
27cb0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
27cc0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
27cd0 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
27ce0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
27cf0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
27d00 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
27d10 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
27d20 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
27d30 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
27d40 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
27d50 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
27d60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
27d70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
27d80 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
27d90 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
27da0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
27db0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
27dc0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
27dd0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
27de0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
27df0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
27e00 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
27e10 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
27e20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
27e30 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
27e40 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
27e50 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
27e60 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
27e70 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
27e80 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
27e90 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
27ea0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
27eb0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27ec0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
27ed0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
27ee0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
27ef0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
27f00 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
27f10 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
27f20 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
27f30 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
27f40 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
27f50 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
27f60 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
27f70 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
27f80 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
27f90 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
27fa0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
27fb0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
27fc0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
27fd0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
27fe0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
27ff0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
28000 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
28010 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28020 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
28030 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
28040 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
28050 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
28060 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
28070 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
28080 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
28090 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
280a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
280b0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
280c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
280d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
280e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
280f0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
28100 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28110 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
28120 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
28130 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
28140 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
28150 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
28160 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
28170 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
28180 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
28190 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
281a0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
281b0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
281c0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
281d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
281e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
281f0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
28200 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
28210 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
28220 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
28230 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
28240 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
28250 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
28260 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
28270 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
28280 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
28290 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
282a0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
282b0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
282c0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
282d0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
282e0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
282f0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
28300 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
28310 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
28320 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
28330 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
28340 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
28350 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
28360 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
28370 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
28380 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
28390 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
283a0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
283b0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
283c0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
283d0 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
283e0 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
283f0 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
28400 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
28410 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
28420 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
28430 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
28440 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
28450 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
28460 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
28470 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
28480 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28490 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
284a0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
284b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
284c0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
284d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
284e0 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
284f0 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
28500 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
28510 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
28520 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
28530 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
28540 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
28550 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
28560 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
28570 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
28580 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
28590 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
285a0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
285b0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
285c0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
285d0 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
285e0 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
285f0 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
28600 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
28610 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
28620 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
28630 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
28640 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
28650 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
28660 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
28670 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
28680 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
28690 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
286a0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
286b0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
286c0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
286d0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
286e0 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
286f0 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
28700 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
28710 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
28720 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
28730 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
28740 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
28750 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
28760 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
28770 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
28780 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28790 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
287a0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
287b0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
287c0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
287d0 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
287e0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
287f0 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
28800 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
28810 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
28820 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
28830 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
28840 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
28850 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
28860 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
28870 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
28880 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
28890 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
288a0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
288b0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
288c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
288d0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
288e0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
288f0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
28900 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28910 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28920 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28930 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28940 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28950 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28960 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28970 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28980 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
28990 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
289a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
289b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
289c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
289d0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
289e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
289f0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
28a00 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
28a10 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
28a20 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
28a30 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
28a40 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28a50 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
28a60 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28a70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28a80 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28a90 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28aa0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28ab0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28ac0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28ad0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28ae0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
28af0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28b00 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28b10 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28b20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28b30 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
28b40 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28b50 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
28b60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28b70 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28b80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28b90 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28ba0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28bb0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
28bc0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28bd0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28be0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28bf0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28c00 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28c10 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28c20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28c30 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28c40 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
28c50 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
28c60 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
28c70 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
28c80 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
28c90 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
28ca0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28cb0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
28cc0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
28cd0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
28ce0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
28cf0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
28d00 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
28d10 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
28d20 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28d30 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28d40 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28d50 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
28d60 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
28d70 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
28d80 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
28d90 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
28da0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
28db0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
28dc0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
28dd0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
28de0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
28df0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
28e00 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
28e10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28e20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28e30 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
28e40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
28e50 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
28e60 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
28e70 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
28e80 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
28e90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28ea0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
28eb0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
28ec0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
28ed0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
28ee0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
28ef0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28f00 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
28f10 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
28f20 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
28f30 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c   sqlite3_sql(sql
28f40 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28f60 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
28f70 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
28f80 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
28f90 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
28fa0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
28fb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
28fc0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
28fd0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
28fe0 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
28ff0 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
29000 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
29010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
29020 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
29030 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
29040 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
29050 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
29060 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
29070 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29080 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29090 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
290a0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
290b0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
290c0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
290d0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
290e0 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
290f0 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
29100 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
29110 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
29120 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
29130 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
29140 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
29150 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
29160 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
29170 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
29180 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
29190 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
291a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
291b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
291c0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
291d0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
291e0 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
291f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
29200 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
29210 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
29220 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
29230 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
29240 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
29250 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
29260 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
29270 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
29280 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
29290 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
292a0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
292b0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
292c0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
292d0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
292e0 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
292f0 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
29300 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
29310 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
29320 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
29330 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
29340 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
29350 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
29360 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
29370 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
29380 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
29390 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
293a0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
293b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
293c0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
293d0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
293e0 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
293f0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
29400 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
29410 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
29420 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
29430 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
29440 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
29450 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
29460 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
29470 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
29480 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
29490 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
294a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
294b0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
294c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
294d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
294e0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
294f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
29500 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
29510 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
29520 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
29530 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
29540 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
29550 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
29560 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29570 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
29580 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29590 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
295a0 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
295b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
295c0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
295d0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
295e0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
295f0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
29600 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
29610 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
29620 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
29630 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
29640 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
29650 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
29660 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
29670 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
29680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
29690 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
296a0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
296b0 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
296c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
296d0 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
296e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
296f0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
29700 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
29710 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29720 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
29730 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
29740 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
29750 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
29760 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
29770 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
29780 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
29790 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
297a0 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
297b0 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
297c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
297d0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
297e0 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
297f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
29800 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
29810 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
29820 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
29830 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
29840 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
29850 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
29860 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
29870 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
29880 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
29890 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
298a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
298b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
298c0 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  L sqlite3_stmt_b
298d0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
298e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
298f0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
29900 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
29910 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
29920 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
29930 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
29940 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29950 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
29960 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
29970 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29980 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
29990 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
299a0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
299b0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
299c0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
299d0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
299e0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
299f0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
29a00 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
29a10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29a20 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
29a30 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
29a40 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
29a50 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
29a60 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
29a70 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
29a80 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
29a90 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
29aa0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
29ab0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
29ac0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
29ad0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
29ae0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
29af0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
29b00 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
29b10 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
29b20 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
29b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
29b40 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
29b50 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
29b60 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
29b70 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
29b80 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
29b90 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
29ba0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
29bb0 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a  e3_value.  The.*
29bc0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
29bd0 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63  _dup()] interfac
29be0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
29bf0 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77   construct a new
29c00 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73   .** protected s
29c10 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f  qlite3_value fro
29c20 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  m an unprotected
29c30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
29c40 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
29c50 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
29c60 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
29c70 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
29c80 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
29c90 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
29ca0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
29cb0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
29cc0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29cd0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
29ce0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
29cf0 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
29d00 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
29d10 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
29d20 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
29d30 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
29d40 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
29d50 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
29d60 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
29d70 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
29d80 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
29d90 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
29da0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
29db0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
29dc0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
29dd0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
29de0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
29df0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
29e00 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
29e10 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
29e20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
29e30 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
29e40 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
29e50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
29e60 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
29e70 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
29e80 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
29e90 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
29ea0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
29eb0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
29ec0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
29ed0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
29ee0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
29ef0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
29f00 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
29f10 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29f20 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29f30 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
29f40 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
29f50 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
29f60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29f70 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
29f80 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
29f90 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
29fa0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
29fb0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
29fc0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
29fd0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
29fe0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
29ff0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a000 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2a010 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a020 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2a030 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2a040 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a050 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2a060 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2a070 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2a080 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2a090 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a0a0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2a0b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2a0c0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2a0d0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2a0e0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2a0f0 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2a100 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a110 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2a120 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a130 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2a140 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2a150 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2a160 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2a170 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2a180 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2a190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2a1a0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2a1b0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2a1c0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2a1d0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2a1e0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2a1f0 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2a200 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2a210 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2a220 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a230 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2a240 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2a250 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2a260 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2a270 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2a280 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2a290 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2a2a0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a2b0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2a2c0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2a2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2a2e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2a2f0 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2a300 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2a310 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2a320 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2a330 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a340 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2a350 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a360 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2a370 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2a380 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2a390 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2a3a0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2a3b0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2a3c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2a3d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2a3e0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2a3f0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2a400 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a410 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2a420 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2a430 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2a440 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2a450 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48  binding}.** METH
2a460 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2a470 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20  .**.** ^(In the 
2a480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
2a490 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  xt input to [sql
2a4a0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2a4b0 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61  )] and its varia
2a4c0 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73  nts,.** literals
2a4d0 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64   may be replaced
2a4e0 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72   by a [parameter
2a4f0 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f  ] that matches o
2a500 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a  ne of following.
2a510 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a  ** templates:.**
2a520 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2a530 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e    ?.** <li>  ?NN
2a540 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a  N.** <li>  :VVV.
2a550 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a  ** <li>  @VVV.**
2a560 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c   <li>  $VVV.** <
2a570 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68  /ul>.**.** In th
2a580 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76  e templates abov
2a590 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74  e, NNN represent
2a5a0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74  s an integer lit
2a5b0 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56  eral,.** and VVV
2a5c0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61   represents an a
2a5d0 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e  lphanumeric iden
2a5e0 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20  tifier.)^  ^The 
2a5f0 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a  values of these.
2a600 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61  ** parameters (a
2a610 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74  lso called "host
2a620 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73   parameter names
2a630 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65  " or "SQL parame
2a640 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65  ters").** can be
2a650 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73   set using the s
2a660 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2a670 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64  routines defined
2a680 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   here..**.** ^Th
2a690 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a6a0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2a6b0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2a6c0 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61  s is always.** a
2a6d0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
2a6e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2a6f0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66  bject returned f
2a700 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  rom.** [sqlite3_
2a710 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2a720 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a   its variants..*
2a730 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2a740 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a750 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51   index of the SQ
2a760 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  L parameter to b
2a770 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  e set..** ^The l
2a780 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61  eftmost SQL para
2a790 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2a7a0 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20  ex of 1.  ^When 
2a7b0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a  the same named.*
2a7c0 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  * SQL parameter 
2a7d0 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61  is used more tha
2a7e0 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61  n once, second a
2a7f0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a  nd subsequent.**
2a800 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76   occurrences hav
2a810 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78  e the same index
2a820 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63   as the first oc
2a830 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68  currence..** ^Th
2a840 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65  e index for name
2a850 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e  d parameters can
2a860 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73   be looked up us
2a870 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
2a880 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a890 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20  er_index()] API 
2a8a0 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68  if desired.  ^Th
2a8b0 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22  e index.** for "
2a8c0 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73  ?NNN" parameters
2a8d0 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66   is the value of
2a8e0 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e   NNN..** ^The NN
2a8f0 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20  N value must be 
2a900 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68  between 1 and th
2a910 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  e [sqlite3_limit
2a920 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ()].** parameter
2a930 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56   [SQLITE_LIMIT_V
2a940 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20  ARIABLE_NUMBER] 
2a950 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20  (default value: 
2a960 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  999)..**.** ^The
2a970 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
2a980 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  is the value to 
2a990 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61  bind to the para
2a9a0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  meter..** ^If th
2a9b0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2a9c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2a9d0 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2a9e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2a9f0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2aa00 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61  bind_blob() is a
2aa10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
2aa20 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  en the fourth pa
2aa30 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67  rameter.** is ig
2aa40 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e  nored and the en
2aa50 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20  d result is the 
2aa60 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f  same as sqlite3_
2aa70 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a  bind_null()..**.
2aa80 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
2aa90 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
2aaa0 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
2aab0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
2aac0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2aad0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
2aae0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
2aaf0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
2ab00 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2ab10 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
2ab20 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
2ab30 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2ab40 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
2ab50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
2ab60 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2ab70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ab80 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2ab90 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2aba0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2abb0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
2abc0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2abd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2abe0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2abf0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2ac00 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
2ac10 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ac20 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2ac30 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
2ac40 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
2ac50 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2ac60 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
2ac70 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
2ac80 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
2ac90 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
2aca0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2acb0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2acc0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20  ind_text16() or 
2acd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ace0 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68  t64() then.** th
2acf0 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  at parameter mus
2ad00 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
2ad10 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68  fset.** where th
2ad20 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
2ad30 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73   would occur ass
2ad40 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67  uming the string
2ad50 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72   were NUL.** ter
2ad60 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
2ad70 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
2ad80 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66  occur at byte of
2ad90 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20  fsets less than 
2ada0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66  .** the value of
2adb0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2adc0 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72  meter then the r
2add0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
2ade0 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f  value will.** co
2adf0 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
2ae00 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74  ULs.  The result
2ae10 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
2ae20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67  involving string
2ae30 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64  s.** with embedd
2ae40 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
2ae50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2ae60 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2ae70 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20  to the BLOB and 
2ae80 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69  string binding i
2ae90 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
2aea0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
2aeb0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
2aec0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
2aed0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
2aee0 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
2aef0 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
2af00 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
2af10 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
2af20 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2af30 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
2af40 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64  the call to bind
2af50 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e   API fails..** ^
2af60 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
2af70 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
2af80 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
2af90 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
2afa0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
2afb0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
2afc0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
2afd0 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
2afe0 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
2aff0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2b000 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
2b010 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2b020 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
2b030 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
2b040 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
2b050 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
2b060 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2b070 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
2b080 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
2b090 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2b0a0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
2b0b0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2b0c0 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74  e sixth argument
2b0d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2b0e0 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62  _text64() must b
2b0f0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c  e one of.** [SQL
2b100 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
2b110 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
2b120 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
2b130 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
2b140 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74  .** to specify t
2b150 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74  he encoding of t
2b160 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74  he text in the t
2b170 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20  hird parameter. 
2b180 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68   If.** the sixth
2b190 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2b1a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2b1b0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
2b1c0 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20   the.** allowed 
2b1d0 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f  values shown abo
2b1e0 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65  ve, or if the te
2b1f0 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  xt encoding is d
2b200 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d  ifferent.** from
2b210 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
2b220 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73  ecified by the s
2b230 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  ixth parameter, 
2b240 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2b250 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  r.** is undefine
2b260 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
2b270 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
2b280 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
2b290 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
2b2a0 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
2b2b0 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
2b2c0 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
2b2d0 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
2b2e0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
2b2f0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
2b300 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
2b310 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
2b320 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
2b330 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
2b340 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
2b350 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
2b360 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
2b370 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
2b380 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
2b390 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
2b3a0 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
2b3b0 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
2b3c0 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
2b3d0 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
2b3e0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
2b3f0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
2b400 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
2b410 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
2b420 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
2b430 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2b440 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2b450 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
2b460 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
2b470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b480 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
2b490 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b4a0 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
2b4b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2b4c0 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
2b4d0 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
2b4e0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
2b4f0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
2b500 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
2b510 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
2b520 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
2b530 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
2b540 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
2b550 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2b560 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
2b570 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
2b580 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
2b590 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2b5a0 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
2b5b0 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
2b5c0 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
2b5d0 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
2b5e0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
2b5f0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
2b600 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
2b610 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
2b620 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
2b630 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
2b640 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
2b650 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
2b660 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
2b670 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
2b680 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
2b690 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f  ..** ^[SQLITE_TO
2b6a0 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72  OBIG] might be r
2b6b0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73  eturned if the s
2b6c0 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20  ize of a string 
2b6d0 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65  or BLOB.** excee
2b6e0 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65  ds limits impose
2b6f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  d by [sqlite3_li
2b700 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
2b710 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a  IT_LENGTH]) or.*
2b720 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  * [SQLITE_MAX_LE
2b730 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  NGTH]..** ^[SQLI
2b740 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74  TE_RANGE] is ret
2b750 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72  urned if the par
2b760 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20  ameter.** index 
2b770 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e  is out of range.
2b780 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d    ^[SQLITE_NOMEM
2b790 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2b7a0 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e   malloc() fails.
2b7b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b7c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2b7d0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2b7e0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b7f0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2b800 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  me()], and [sqli
2b810 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2b820 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2b830 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2b840 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2b850 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
2b860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b870 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
2b880 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
2b890 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2b8a0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b8b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b8c0 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
2b8d0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b8e0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
2b8f0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
2b900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b910 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
2b920 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2b930 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2b940 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2b950 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2b960 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2b970 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
2b980 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b990 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  L sqlite3_bind_i
2b9a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2b9b0 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
2b9c0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2b9d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2b9e0 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2b9f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ba00 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2ba10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ba20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2ba30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2ba40 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2ba50 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
2ba60 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2ba70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2ba80 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
2ba90 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  tmt*,int,const c
2baa0 68 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29  har*,int,void(*)
2bab0 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45  (void*));.SQLITE
2bac0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2bad0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2bae0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
2baf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2bb00 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2bb10 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2bb20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2bb30 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2bb40 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2bb50 78 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt64(sqlite3_stm
2bb60 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63  t*, int, const c
2bb70 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  har*, sqlite3_ui
2bb80 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2bb90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2bba0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75  oid(*)(void*), u
2bbb0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63  nsigned char enc
2bbc0 6f 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41  oding);.SQLITE_A
2bbd0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2bbe0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2bbf0 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  nd_value(sqlite3
2bc00 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2bc10 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  st sqlite3_value
2bc20 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
2bc30 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2bc40 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  L sqlite3_bind_z
2bc50 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2bc60 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2bc70 6e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  n);.SQLITE_API i
2bc80 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2bc90 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  L sqlite3_bind_z
2bca0 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
2bcb0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2bcc0 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
2bcd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2bce0 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2bcf0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
2bd00 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2bd10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
2bd20 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
2bd30 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
2bd40 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
2bd50 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
2bd60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2bd70 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
2bd80 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
2bd90 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
2bda0 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
2bdb0 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
2bdc0 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
2bdd0 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
2bde0 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
2bdf0 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
2be00 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
2be10 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
2be20 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
2be30 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
2be40 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
2be50 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
2be60 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2be70 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
2be80 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
2be90 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
2bea0 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
2beb0 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
2bec0 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
2bed0 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
2bee0 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
2bef0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2bf00 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
2bf10 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
2bf20 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
2bf30 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
2bf40 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2bf50 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2bf60 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2bf70 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bf80 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
2bf90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2bfa0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bfb0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2bfc0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2bfd0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2bfe0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bff0 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2c000 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c010 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2c020 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2c030 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2c040 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2c050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2c060 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c070 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2c080 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2c090 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2c0a0 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2c0b0 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2c0c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2c0d0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2c0e0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2c0f0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2c100 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2c110 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2c120 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2c130 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2c140 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2c150 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2c160 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2c170 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2c180 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2c190 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2c1a0 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2c1b0 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2c1c0 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2c1d0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2c1e0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2c1f0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2c200 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2c210 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2c220 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2c230 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2c240 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2c250 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2c260 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2c270 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2c280 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2c290 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2c2a0 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2c2b0 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2c2c0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2c2d0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2c2e0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2c2f0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2c300 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2c310 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2c320 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2c330 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2c340 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2c350 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2c360 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2c370 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2c380 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2c390 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c3a0 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2c3b0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2c3c0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c3d0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2c3e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c3f0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2c400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c410 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2c420 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2c430 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2c440 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2c450 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c460 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
2c470 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
2c480 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c490 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
2c4a0 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
2c4b0 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
2c4c0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c4d0 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2c4e0 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2c4f0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2c500 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2c510 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2c520 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2c530 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2c540 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2c550 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2c560 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2c570 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2c580 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2c590 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2c5a0 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2c5b0 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2c5c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2c5d0 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2c5e0 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2c5f0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2c600 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2c610 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2c620 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2c630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c640 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2c650 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c660 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2c670 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2c680 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c690 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2c6a0 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2c6b0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c6c0 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _name()]..*/.SQL
2c6d0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2c6e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2c6f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c700 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2c710 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2c720 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2c730 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2c740 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2c750 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2c760 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2c770 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c780 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2c790 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2c7a0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2c7b0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2c7c0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2c7d0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c7e0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2c7f0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2c800 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2c810 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2c820 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2c830 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2c840 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
2c850 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c860 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2c870 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2c880 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2c890 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c8a0 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2c8b0 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c8c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c8d0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c8e0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2c8f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c900 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2c910 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c920 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2c930 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2c940 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2c950 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2c960 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2c970 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2c980 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2c990 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2c9a0 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2c9b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2c9c0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2c9d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2c9e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2c9f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2ca00 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2ca10 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2ca20 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2ca30 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2ca40 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2ca50 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ca60 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2ca70 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2ca80 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2ca90 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2caa0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2cab0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2cac0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2cad0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2cae0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2caf0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2cb00 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2cb10 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2cb20 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2cb30 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2cb40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2cb50 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2cb60 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2cb70 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2cb80 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2cb90 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2cba0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cbb0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2cbc0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2cbd0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2cbe0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2cbf0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2cc00 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2cc10 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2cc20 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2cc30 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2cc40 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2cc50 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2cc60 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2cc70 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2cc80 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2cc90 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2cca0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ccb0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2ccc0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2ccd0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2cce0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2ccf0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2cd00 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2cd10 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2cd20 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2cd30 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2cd40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cd50 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2cd60 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2cd70 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2cd80 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2cd90 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2cda0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2cdb0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2cdc0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2cdd0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2cde0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2cdf0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2ce00 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2ce10 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2ce20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2ce30 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2ce40 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2ce50 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2ce60 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2ce70 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2ce80 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2ce90 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2cea0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2ceb0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2cec0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2ced0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2cee0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2cef0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2cf00 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2cf10 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2cf20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2cf30 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2cf40 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2cf50 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2cf60 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cf70 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
2cf80 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2cf90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2cfa0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2cfb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2cfc0 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2cfd0 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2cfe0 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2cff0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2d000 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d010 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2d020 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2d030 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2d040 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2d050 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2d060 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2d070 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2d080 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2d090 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2d0a0 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2d0b0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2d0c0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2d0d0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2d0e0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2d0f0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2d100 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2d110 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2d120 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2d130 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2d140 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2d150 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2d160 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2d170 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2d180 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2d190 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2d1a0 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2d1b0 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2d1c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2d1d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2d1e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d1f0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2d200 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2d210 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2d220 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2d230 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2d240 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2d250 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2d260 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2d270 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2d280 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2d290 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2d2a0 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2d2b0 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2d2c0 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2d2d0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2d2e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2d2f0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2d300 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2d310 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2d320 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2d330 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2d340 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2d350 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2d360 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2d370 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2d380 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d390 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2d3a0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2d3b0 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2d3c0 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2d3d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d3e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2d3f0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2d400 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2d410 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2d420 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2d430 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2d440 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2d450 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2d460 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2d470 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2d480 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2d490 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2d4a0 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2d4b0 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2d4c0 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2d4d0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2d4e0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2d4f0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2d500 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2d510 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2d520 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2d530 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2d540 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2d550 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2d560 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2d570 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2d580 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2d590 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2d5a0 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2d5b0 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2d5c0 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2d5d0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2d5e0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2d5f0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2d600 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2d610 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2d620 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2d630 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2d640 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2d650 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2d660 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2d670 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2d680 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2d690 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2d6a0 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2d6b0 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2d6c0 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2d6d0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d6e0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d6f0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2d700 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2d710 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2d720 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2d730 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2d740 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d750 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2d760 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2d770 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2d780 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2d790 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2d7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d7b0 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2d7c0 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2d7d0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2d7e0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2d7f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d800 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2d810 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2d820 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d830 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2d840 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2d850 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2d860 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d870 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2d880 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2d890 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d8a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d8b0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2d8c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2d8d0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d8e0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d8f0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2d900 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2d910 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2d930 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2d940 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d950 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d960 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2d970 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d980 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2d990 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d9a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d9b0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d9c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d9d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d9e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d9f0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2da00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2da10 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2da20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2da30 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2da40 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2da50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2da60 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2da70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2da80 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2da90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2daa0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2dab0 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2dac0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2dad0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2dae0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2daf0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2db00 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2db10 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2db20 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2db30 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2db40 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2db50 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2db60 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2db70 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2db80 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2db90 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2dba0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2dbb0 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2dbc0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2dbd0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2dbe0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2dbf0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2dc00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2dc10 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2dc20 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2dc30 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2dc40 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2dc50 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2dc60 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2dc70 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2dc80 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2dc90 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2dca0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2dcb0 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2dcc0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2dcd0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2dce0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2dcf0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2dd00 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2dd10 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2dd20 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2dd30 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2dd40 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2dd50 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2dd60 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2dd70 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2dd80 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2dd90 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2dda0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2ddb0 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2ddc0 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2ddd0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2dde0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2ddf0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2de00 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2de10 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2de20 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2de30 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2de40 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2de50 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2de60 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2de70 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2de80 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2de90 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2dea0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2deb0 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2dec0 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2ded0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2dee0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2def0 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
2df00 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2df10 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2df20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2df30 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2df40 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2df50 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2df60 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2df70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2df80 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2df90 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2dfa0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2dfb0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2dfc0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2dfd0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2dfe0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2dff0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e000 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2e010 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2e020 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2e030 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2e040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e050 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2e060 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2e070 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2e080 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2e090 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2e0a0 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2e0b0 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2e0c0 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2e0d0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2e0e0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2e0f0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2e100 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2e110 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2e120 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2e130 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2e140 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2e150 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2e160 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2e170 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2e180 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2e190 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e1a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2e1b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2e1c0 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2e1d0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2e1e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2e1f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2e200 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2e210 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2e220 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2e230 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2e240 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2e250 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2e260 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2e270 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2e280 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2e290 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2e2a0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2e2b0 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2e2c0 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2e2d0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2e2e0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2e2f0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2e300 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2e310 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2e320 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2e330 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2e340 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2e350 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2e360 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2e370 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2e380 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2e390 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2e3a0 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2e3b0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2e3c0 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2e3d0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2e3e0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2e3f0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2e400 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2e410 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2e420 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2e430 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2e440 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2e450 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2e460 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2e470 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2e480 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2e490 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2e4a0 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2e4b0 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2e4c0 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2e4d0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2e4e0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2e4f0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2e500 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2e510 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2e520 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2e530 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2e540 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2e550 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2e560 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2e570 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2e580 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2e590 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2e5a0 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2e5b0 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2e5c0 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2e5d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2e5e0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2e5f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2e600 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2e610 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2e620 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2e630 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2e640 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2e650 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2e660 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2e670 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2e680 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2e690 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2e6a0 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2e6b0 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2e6c0 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2e6d0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2e6e0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2e6f0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2e700 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e710 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2e720 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2e730 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2e740 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2e750 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2e760 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2e770 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2e780 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2e790 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2e7a0 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2e7b0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2e7c0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2e7d0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2e7e0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2e7f0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2e800 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2e810 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2e820 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2e830 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2e840 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2e850 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2e860 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2e870 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2e880 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2e890 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2e8a0 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2e8b0 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2e8c0 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2e8d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2e8e0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2e8f0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2e900 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2e910 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2e920 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2e930 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2e940 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2e950 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2e960 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2e970 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2e980 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2e990 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2e9a0 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2e9b0 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2e9c0 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2e9d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e9e0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2e9f0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2ea00 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2ea10 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2ea20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2ea30 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2ea40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2ea50 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2ea60 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2ea70 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2ea80 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2ea90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2eaa0 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2eab0 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2eac0 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2ead0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2eae0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2eaf0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2eb00 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2eb10 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2eb20 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2eb30 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2eb40 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2eb50 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2eb60 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2eb70 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2eb80 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2eb90 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2eba0 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2ebb0 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2ebc0 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2ebd0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2ebe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ebf0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2ec00 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2ec10 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2ec20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2ec30 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2ec40 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2ec50 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2ec60 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2ec70 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2ec80 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2ec90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2eca0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2ecb0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2ecc0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2ecd0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2ece0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2ecf0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2ed00 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2ed10 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2ed20 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2ed30 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2ed40 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2ed50 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2ed60 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2ed70 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2ed80 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2ed90 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2eda0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2edb0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2edc0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2edd0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2ede0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2edf0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2ee00 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2ee10 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2ee20 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2ee30 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2ee40 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2ee50 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2ee60 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2ee70 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2ee80 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2ee90 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2eea0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2eeb0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2eec0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2eed0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eee0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2eef0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2ef00 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2ef10 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2ef20 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2ef30 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2ef40 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2ef50 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2ef60 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2ef70 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2ef80 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2ef90 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2efa0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2efb0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2efc0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2efd0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2efe0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2eff0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2f000 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2f010 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2f020 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2f030 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2f040 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2f050 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2f060 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2f070 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2f080 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2f090 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2f0a0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2f0b0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2f0c0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2f0d0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2f0e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f0f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2f100 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  LL sqlite3_step(
2f110 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2f120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2f130 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2f140 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2f150 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2f160 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2f170 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2f180 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2f190 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2f1a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2f1b0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2f1c0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2f1d0 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2f1e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f1f0 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2f200 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f210 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2f220 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2f230 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2f240 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2f250 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2f260 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2f270 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2f280 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2f290 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2f2a0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2f2b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f2c0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2f2d0 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2f2e0 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2f2f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2f300 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2f310 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2f320 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2f330 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2f340 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f350 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2f360 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2f370 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f380 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2f390 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2f3a0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2f3b0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2f3c0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2f3d0 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2f3e0 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2f3f0 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2f400 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2f410 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2f420 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2f430 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2f440 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2f450 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2f460 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2f470 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2f480 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2f490 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2f4a0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2f4b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2f4c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f4d0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f4e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f4f0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f500 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2f510 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2f520 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2f530 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2f540 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2f550 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2f560 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2f570 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2f580 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2f590 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2f5a0 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2f5b0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2f5c0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2f5d0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2f5e0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2f5f0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2f600 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2f610 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2f620 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2f630 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2f640 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2f650 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2f660 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2f670 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2f680 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2f690 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2f6a0 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2f6b0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2f6c0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2f6d0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2f6e0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2f6f0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2f700 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2f710 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2f720 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2f730 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2f740 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2f750 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2f760 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2f770 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2f780 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2f790 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2f7a0 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2f7b0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2f7c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2f7d0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2f7e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2f7f0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2f800 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2f810 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2f820 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2f830 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2f840 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2f850 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f860 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f870 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2f880 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2f890 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2f8a0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2f8b0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2f8c0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2f8d0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2f8e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2f8f0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2f900 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2f910 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2f920 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2f930 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2f940 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2f950 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2f960 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2f970 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2f980 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2f990 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2f9a0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f9b0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f9c0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2f9d0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2f9e0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2f9f0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2fa00 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2fa10 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2fa20 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2fa30 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2fa40 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2fa50 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2fa60 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2fa70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2fa80 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2fa90 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2faa0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2fab0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2fac0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2fad0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2fae0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2faf0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2fb00 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2fb10 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2fb20 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2fb30 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2fb40 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2fb50 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2fb60 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2fb70 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2fb80 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2fb90 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2fba0 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2fbb0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2fbc0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2fbd0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2fbe0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2fbf0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2fc00 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2fc10 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2fc20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fc30 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2fc40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fc50 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2fc60 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2fc70 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2fc80 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2fc90 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2fca0 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2fcb0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2fcc0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2fcd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2fce0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2fcf0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2fd00 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2fd10 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2fd20 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2fd30 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2fd40 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2fd50 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2fd60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2fd70 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2fd80 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2fd90 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2fda0 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2fdb0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2fdc0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2fdd0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2fde0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2fdf0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2fe00 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2fe10 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2fe20 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2fe30 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2fe40 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2fe50 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2fe60 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2fe70 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2fe80 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2fe90 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2fea0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2feb0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2fec0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2fed0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2fee0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2fef0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2ff00 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ff10 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2ff20 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2ff30 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2ff40 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2ff50 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2ff60 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2ff70 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2ff80 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2ff90 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2ffa0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ffb0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2ffc0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2ffd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ffe0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2fff0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
30000 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
30010 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
30020 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
30030 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
30040 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
30050 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
30060 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
30070 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
30080 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
30090 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
300a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
300b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
300c0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
300d0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
300e0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
300f0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
30100 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
30110 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
30120 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
30130 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
30140 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
30150 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
30160 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
30170 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
30180 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
30190 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
301a0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
301b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
301c0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
301d0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
301e0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
301f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
30200 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
30210 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
30220 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
30230 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
30240 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
30250 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
30260 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
30270 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30280 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
30290 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
302a0 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
302b0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
302c0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
302d0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
302e0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
302f0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
30300 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
30310 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
30320 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
30330 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
30340 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
30350 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
30360 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
30370 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
30380 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
30390 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
303a0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
303b0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
303c0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
303d0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
303e0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
303f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
30400 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
30410 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30420 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
30430 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
30440 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
30450 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
30460 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
30470 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
30480 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
30490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
304a0 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
304b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
304c0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
304d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
304e0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
304f0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
30500 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
30510 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
30520 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
30530 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30540 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30550 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
30560 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
30570 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
30580 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
30590 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
305a0 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
305b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
305c0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
305d0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
305e0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
305f0 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
30600 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
30610 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
30620 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
30630 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
30640 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
30650 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
30660 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
30670 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
30680 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
30690 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
306a0 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
306b0 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
306c0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
306d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
306e0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
306f0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
30700 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
30710 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30720 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
30730 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
30740 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
30750 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
30760 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
30770 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
30780 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
30790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
307a0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
307b0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
307c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
307d0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
307e0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
307f0 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
30800 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
30810 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
30820 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
30830 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
30840 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
30850 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
30860 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
30870 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
30880 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
30890 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
308a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
308b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
308c0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
308d0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
308e0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
308f0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
30900 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
30910 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
30920 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
30930 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
30940 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
30950 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
30960 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
30970 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
30980 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
30990 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
309a0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
309b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
309c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
309d0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
309e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
309f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
30a00 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
30a10 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
30a20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
30a30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
30a40 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
30a50 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
30a60 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
30a70 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
30a80 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
30a90 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
30aa0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
30ab0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30ac0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
30ad0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
30ae0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30af0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
30b00 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
30b10 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
30b20 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
30b30 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
30b40 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
30b50 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
30b60 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
30b70 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
30b80 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30b90 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30ba0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
30bb0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
30bc0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
30bd0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
30be0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
30bf0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
30c00 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
30c10 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
30c20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
30c30 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30c40 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30c50 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
30c60 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30c70 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30c80 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
30c90 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
30ca0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
30cb0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
30cc0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
30cd0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
30ce0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
30cf0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
30d00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30d10 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
30d20 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
30d30 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
30d40 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30d50 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30d60 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
30d70 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
30d80 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
30d90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
30da0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
30db0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
30dc0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
30dd0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
30de0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
30df0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30e00 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
30e10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30e20 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
30e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30e40 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
30e50 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
30e60 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
30e70 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
30e80 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
30e90 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
30ea0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
30eb0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
30ec0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30ed0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
30ee0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30ef0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
30f00 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30f10 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30f20 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
30f30 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
30f40 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
30f50 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
30f60 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
30f70 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
30f80 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
30f90 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
30fa0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30fb0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30fc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30fd0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30fe0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
30ff0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
31000 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
31010 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
31020 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
31030 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
31040 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
31050 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
31060 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
31070 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
31080 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
31090 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
310a0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
310b0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
310c0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
310d0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
310e0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
310f0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
31100 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
31110 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
31120 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
31130 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
31140 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
31150 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
31160 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
31170 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
31180 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
31190 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
311a0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
311b0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
311c0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
311d0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
311e0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
311f0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
31200 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
31210 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
31220 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
31230 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
31240 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
31250 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
31260 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
31270 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
31280 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
31290 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
312a0 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
312b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
312c0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
312d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
312e0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
312f0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
31300 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
31310 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31320 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
31330 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
31340 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
31350 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
31360 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31370 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
31380 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
31390 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
313a0 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
313b0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
313c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
313d0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
313e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
313f0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
31400 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
31410 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
31420 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
31430 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
31440 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
31450 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
31460 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
31470 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
31480 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
31490 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
314a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
314b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
314c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
314d0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
314e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
314f0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
31500 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
31510 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31520 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
31530 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
31540 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31550 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
31560 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
31570 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
31580 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
31590 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
315a0 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
315b0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
315c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
315d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
315e0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
315f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
31600 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
31610 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
31620 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
31630 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
31640 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
31650 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
31660 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
31670 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
31680 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
31690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
316a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
316b0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
316c0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
316d0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
316e0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
316f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
31700 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
31710 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
31720 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
31730 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
31740 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
31750 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
31760 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
31770 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
31780 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
31790 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
317a0 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
317b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
317c0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
317d0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
317e0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
317f0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
31800 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
31810 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
31820 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
31830 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31840 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
31850 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31860 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
31870 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31890 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
318a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
318b0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
318c0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
318d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
318e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
318f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
31900 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49  _API double SQLI
31910 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
31920 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
31930 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31940 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31950 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
31960 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
31970 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
31980 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31990 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
319a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
319b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
319c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
319d0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
319e0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
319f0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
31a00 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c  signed char *SQL
31a10 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31a20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
31a30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31a40 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
31a50 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
31a60 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
31a70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31a80 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
31a90 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31aa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
31ab0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
31ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31ad0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31ae0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31af0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
31b00 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44  alue *SQLITE_STD
31b10 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
31b20 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
31b30 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31b40 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
31b50 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
31b60 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
31b70 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
31b80 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
31b90 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
31ba0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31bb0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31bc0 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
31bd0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31be0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
31bf0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
31c00 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
31c10 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
31c20 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
31c30 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
31c40 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
31c50 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
31c60 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
31c70 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
31c80 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
31c90 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31ca0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
31cb0 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
31cc0 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
31cd0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
31ce0 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
31cf0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
31d00 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
31d10 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
31d20 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
31d30 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31d40 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
31d50 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
31d60 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
31d70 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
31d80 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
31d90 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
31da0 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
31db0 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
31dc0 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
31dd0 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
31de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31df0 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
31e00 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
31e10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
31e20 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
31e30 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
31e40 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
31e50 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
31e60 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
31e70 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
31e80 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
31e90 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
31ea0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
31eb0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
31ec0 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
31ed0 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
31ee0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
31ef0 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
31f00 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
31f10 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
31f20 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
31f30 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
31f40 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
31f50 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
31f60 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
31f70 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
31f80 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
31f90 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
31fa0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
31fb0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
31fc0 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
31fd0 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
31fe0 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
31ff0 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
32000 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
32010 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
32020 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
32030 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
32040 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
32050 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32070 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
32080 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
32090 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
320a0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
320b0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
320c0 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
320d0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
320e0 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
320f0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
32100 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
32110 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
32120 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
32130 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
32140 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
32150 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
32160 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
32170 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
32180 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
32190 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
321a0 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
321b0 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
321c0 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
321d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
321e0 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
321f0 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
32200 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
32210 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
32220 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
32230 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32240 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
32250 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
32260 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
32270 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
32280 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
32290 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
322a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
322b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
322c0 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
322d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
322e0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
322f0 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
32300 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
32310 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
32320 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
32330 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
32340 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
32350 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
32360 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
32370 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
32380 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
32390 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
323a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
323b0 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
323c0 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
323d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
323e0 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
323f0 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
32400 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
32410 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
32420 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
32430 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
32440 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
32450 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
32460 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
32470 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
32480 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
32490 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
324a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
324b0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
324c0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
324d0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
324e0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
324f0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
32500 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
32510 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
32520 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
32530 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
32540 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32550 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
32560 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
32570 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32580 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
32590 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
325a0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
325b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
325c0 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
325d0 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
325e0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
325f0 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
32600 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
32610 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
32620 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
32630 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
32640 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
32650 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
32660 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
32670 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
32680 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
32690 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
326a0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
326b0 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
326c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
326d0 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
326e0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
326f0 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
32700 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
32710 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
32720 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
32730 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
32740 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32750 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32760 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32770 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
32780 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32790 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
327a0 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
327b0 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
327c0 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
327d0 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
327e0 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
327f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
32800 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32810 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
32820 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
32830 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
32840 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32850 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
32860 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
32870 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
32880 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
32890 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
328a0 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
328b0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
328c0 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
328d0 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
328e0 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
328f0 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
32900 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
32910 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
32920 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
32930 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
32940 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
32950 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
32960 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
32970 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
32980 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
32990 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
329a0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
329b0 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
329c0 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
329d0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
329e0 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
329f0 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
32a00 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
32a10 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
32a20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
32a30 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
32a40 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
32a50 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
32a60 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
32a70 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
32a80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
32a90 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
32aa0 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
32ab0 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
32ac0 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
32ad0 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
32ae0 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
32af0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
32b00 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
32b10 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
32b20 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
32b30 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
32b40 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
32b50 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
32b60 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
32b70 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
32b80 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
32b90 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
32ba0 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
32bb0 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
32bc0 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
32bd0 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
32be0 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
32bf0 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
32c00 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
32c10 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
32c20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
32c30 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
32c40 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32c50 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
32c60 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32c70 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
32c80 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
32c90 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
32ca0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
32cb0 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
32cc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32cd0 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
32ce0 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
32cf0 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
32d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32d10 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
32d20 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
32d30 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
32d40 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
32d50 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
32d60 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
32d70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
32d80 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
32d90 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32da0 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
32db0 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
32dc0 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
32dd0 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
32de0 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
32df0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32e00 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32e10 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32e20 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32e30 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
32e40 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
32e50 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
32e60 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
32e70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
32e80 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
32e90 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
32ea0 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
32eb0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
32ec0 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
32ed0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
32ee0 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
32ef0 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
32f00 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
32f10 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
32f20 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
32f30 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
32f40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
32f50 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
32f60 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
32f70 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
32f80 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
32f90 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
32fa0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
32fb0 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
32fc0 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
32fd0 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
32fe0 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
32ff0 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
33000 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
33010 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
33020 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
33030 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
33040 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
33050 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
33060 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
33070 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
33080 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
33090 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
330a0 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
330b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
330c0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
330d0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
330e0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
330f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
33100 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
33110 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
33120 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
33130 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
33140 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
33150 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
33160 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
33170 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
33180 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
33190 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
331a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
331b0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
331c0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
331d0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
331e0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
331f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
33200 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
33210 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
33220 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
33230 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
33240 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
33250 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
33260 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
33270 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33280 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
33290 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
332a0 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
332b0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
332c0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
332d0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
332e0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
332f0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
33300 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
33310 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
33320 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
33330 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
33340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
33350 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33360 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
33370 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
33380 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
33390 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
333a0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
333b0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
333c0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
333d0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
333e0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
333f0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
33400 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
33410 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
33420 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
33430 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
33440 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
33450 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
33460 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
33470 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33480 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
33490 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
334a0 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
334b0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
334c0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
334d0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
334e0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
334f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
33500 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
33510 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
33520 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
33530 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
33540 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
33550 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33560 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
33570 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
33580 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
33590 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
335a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
335b0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
335c0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
335d0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
335e0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
335f0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
33600 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
33610 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
33620 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
33630 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
33640 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
33650 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
33660 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
33670 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
33680 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
33690 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
336a0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
336b0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
336c0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
336d0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
336e0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
336f0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
33700 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
33710 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
33720 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
33730 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
33740 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
33750 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
33760 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
33770 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
33780 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
33790 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
337a0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
337b0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
337c0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
337d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
337e0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
337f0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
33800 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
33810 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
33820 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
33830 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
33840 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
33850 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
33860 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
33870 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
33880 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
33890 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
338a0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
338b0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
338c0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
338d0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
338e0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
338f0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
33900 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
33910 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
33920 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
33930 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
33940 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33950 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
33960 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
33970 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33980 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
33990 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
339a0 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
339b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
339c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
339d0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
339e0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
339f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
33a00 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
33a10 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
33a20 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
33a30 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
33a40 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
33a50 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33a60 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33a70 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
33a80 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33a90 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33aa0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
33ab0 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
33ac0 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
33ad0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33ae0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33af0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
33b00 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
33b10 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
33b20 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
33b30 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
33b40 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
33b50 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
33b60 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
33b70 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33b80 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33b90 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33ba0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33bb0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33bc0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33bd0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
33be0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
33bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
33c00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
33c10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33c20 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
33c30 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
33c40 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
33c50 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
33c60 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
33c70 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
33c80 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
33c90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33ca0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33cb0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
33cc0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
33cd0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33ce0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33cf0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
33d00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
33d10 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
33d20 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
33d30 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
33d40 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
33d50 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
33d60 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
33d70 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
33d80 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
33d90 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
33da0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
33db0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
33dc0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
33dd0 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
33de0 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
33df0 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
33e00 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
33e10 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
33e20 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
33e30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33e40 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
33e50 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
33e60 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
33e70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33e80 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
33e90 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
33ea0 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
33eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
33ec0 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
33ed0 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
33ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33ef0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
33f00 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
33f10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
33f20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
33f30 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
33f40 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
33f50 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
33f60 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
33f70 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
33f80 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
33f90 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
33fa0 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
33fb0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
33fc0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
33fd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33fe0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
33ff0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
34000 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
34010 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
34020 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
34030 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
34040 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
34050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34060 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
34070 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
34080 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
34090 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
340a0 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
340b0 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
340c0 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
340d0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
340e0 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
340f0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
34100 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
34110 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
34120 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
34130 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
34140 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
34150 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
34160 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
34170 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
34180 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
34190 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
341a0 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
341b0 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
341c0 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
341d0 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
341e0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
341f0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
34200 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34210 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34220 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
34230 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
34240 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
34250 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
34260 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34270 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
34280 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
34290 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
342a0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
342b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
342c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
342d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
342e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
342f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
34300 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
34310 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
34320 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  L sqlite3_global
34330 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
34340 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34350 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
34360 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
34370 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
34380 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
34390 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
343a0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
343b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
343c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
343d0 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
343e0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
343f0 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
34400 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
34410 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
34420 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
34430 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
34440 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
34450 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34460 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
34470 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
34480 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
34490 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
344a0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
344b0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
344c0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
344d0 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
344e0 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
344f0 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
34500 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
34510 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
34520 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
34530 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
34540 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
34550 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
34560 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34570 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34580 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34590 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
345a0 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
345b0 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
345c0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
345d0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
345e0 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
345f0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
34600 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
34610 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
34620 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
34630 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
34640 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34650 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
34660 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34670 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
34680 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
34690 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
346a0 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
346b0 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
346c0 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
346d0 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
346e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
346f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
34700 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
34710 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
34720 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34730 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
34740 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
34750 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
34760 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
34770 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34780 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
34790 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
347a0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
347b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
347c0 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
347d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
347e0 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
347f0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
34800 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
34810 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
34820 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
34830 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34840 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
34850 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
34860 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
34870 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
34880 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
34890 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
348a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
348b0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
348c0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
348d0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
348e0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
348f0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
34900 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
34910 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
34920 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
34930 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
34940 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
34950 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
34960 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
34970 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
34980 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
34990 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
349a0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
349b0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
349c0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
349d0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
349e0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
349f0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
34a00 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
34a10 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
34a20 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
34a30 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
34a40 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
34a50 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
34a60 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
34a70 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
34a80 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
34a90 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
34aa0 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
34ab0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
34ac0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
34ad0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
34ae0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
34af0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
34b00 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
34b10 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
34b20 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
34b30 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
34b40 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
34b50 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
34b60 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
34b70 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
34b80 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
34b90 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
34ba0 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
34bb0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
34bc0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
34bd0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
34be0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34bf0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
34c00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34c10 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
34c20 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
34c30 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34c40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34c50 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
34c60 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34c70 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
34c80 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
34c90 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
34ca0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
34cb0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34cc0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
34cd0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
34ce0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
34cf0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
34d00 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
34d10 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34d20 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
34d30 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
34d40 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
34d50 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34d60 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
34d70 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34d80 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
34d90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34da0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
34db0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34dc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34dd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34de0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
34df0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
34e00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  *);.SQLITE_API d
34e10 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44  ouble SQLITE_STD
34e20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34e30 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
34e40 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34e50 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34e60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34e70 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
34e80 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34e90 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
34ea0 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
34eb0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34ec0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
34ed0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34ee0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
34ef0 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  ed char *SQLITE_
34f00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34f10 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
34f20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34f30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34f40 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
34f50 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34f60 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
34f70 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34f80 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
34f90 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34fa0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34fb0 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
34fc0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34fd0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
34fe0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34ff0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
35000 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
35010 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
35020 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
35030 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
35040 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
35050 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35060 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
35070 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
35080 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
35090 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
350a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
350b0 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75 62   Finding The Sub
350c0 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c 75  type Of SQL Valu
350d0 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
350e0 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a  lite3_value.**.*
350f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  * The sqlite3_va
35100 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20 66  lue_subtype(V) f
35110 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
35120 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 0a  the subtype for.
35130 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74 69  ** an [applicati
35140 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
35150 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65 6e  unction] argumen
35160 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79 70  t V.  The subtyp
35170 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
35180 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
35190 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20 61  pass a limited a
351a0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78 74  mount of context
351b0 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51 4c   from.** one SQL
351c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e 6f   function to ano
351d0 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20 5b  ther.  Use the [
351e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73  sqlite3_result_s
351f0 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f 75  ubtype()].** rou
35200 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65 20  tine to set the 
35210 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65 20  subtype for the 
35220 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35230 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  an SQL function.
35240 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  .**.** SQLite ma
35250 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73 75  kes no use of su
35260 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20 49  btype itself.  I
35270 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73 20  t merely passes 
35280 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 66  the subtype.** f
35290 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20 6f  rom the result o
352a0 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74 69  f one [applicati
352b0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
352c0 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74 68  unction] into th
352d0 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61 6e  e.** input of an
352e0 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  other..*/.SQLITE
352f0 5f 41 50 49 20 75 6e 73 69 67 6e 65 64 20 69 6e  _API unsigned in
35300 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
35310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73   sqlite3_value_s
35320 75 62 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  ubtype(sqlite3_v
35330 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
35340 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20 41 6e  API3REF: Copy An
35350 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c 75 65  d Free SQL Value
35360 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
35370 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a  ite3_value.**.**
35380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
35390 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
353a0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
353b0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
353c0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
353d0 63 74 20 44 20 61 6e 64 20 72 65 74 75 72 6e 73  ct D and returns
353e0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
353f0 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65 20 5b  at copy.  ^The [
35400 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 72  sqlite3_value] r
35410 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 61 20  eturned.** is a 
35420 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
35430 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35440 20 65 76 65 6e 20 69 66 20 74 68 65 20 69 6e 70   even if the inp
35450 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54  ut is not..** ^T
35460 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
35470 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63  _dup(V) interfac
35480 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69  e returns NULL i
35490 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72 20 69  f V is NULL or i
354a0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
354b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2e 0a  location fails..
354c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
354d0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
354e0 20 69 6e 74 65 72 66 61 63 65 20 66 72 65 65 73   interface frees
354f0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   an [sqlite3_val
35500 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 72  ue] object.** pr
35510 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
35520 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35530 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20 20 5e  value_dup()].  ^
35540 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c 20 70  If V is a NULL p
35550 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e 20 73  ointer.** then s
35560 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
35570 65 28 56 29 20 69 73 20 61 20 68 61 72 6d 6c 65  e(V) is a harmle
35580 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c  ss no-op..*/.SQL
35590 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
355a0 58 50 45 52 49 4d 45 4e 54 41 4c 20 73 71 6c 69  XPERIMENTAL sqli
355b0 74 65 33 5f 76 61 6c 75 65 20 2a 53 51 4c 49 54  te3_value *SQLIT
355c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
355d0 33 5f 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73  3_value_dup(cons
355e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
355f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
35600 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
35610 4c 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  L void SQLITE_ST
35620 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
35630 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
35640 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
35650 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
35660 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
35670 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
35680 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35690 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
356a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
356b0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
356c0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
356d0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
356e0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
356f0 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
35700 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
35710 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
35720 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
35730 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35740 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
35750 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
35760 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
35770 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
35780 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
35790 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
357a0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
357b0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
357c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
357d0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
357e0 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
357f0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
35800 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
35810 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35820 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
35830 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
35840 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
35850 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
35860 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
35870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
35880 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
35890 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
358a0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
358b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
358c0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
358d0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
358e0 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
358f0 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
35900 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
35910 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
35920 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
35930 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
35940 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
35950 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
35960 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
35970 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
35980 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
35990 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
359a0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
359b0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
359c0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
359d0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
359e0 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
359f0 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
35a00 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
35a10 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
35a20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35a30 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35a40 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
35a50 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
35a60 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
35a70 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
35a80 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
35a90 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
35aa0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
35ab0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
35ac0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
35ad0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
35ae0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
35af0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
35b00 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35b10 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
35b20 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
35b30 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
35b40 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
35b50 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
35b60 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
35b70 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35b80 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
35b90 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
35ba0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
35bb0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
35bc0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
35bd0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
35be0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
35bf0 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
35c00 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
35c10 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
35c20 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
35c30 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
35c40 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35c50 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
35c60 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
35c70 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
35c80 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
35c90 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
35ca0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
35cb0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
35cc0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
35cd0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35ce0 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
35cf0 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
35d00 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
35d10 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
35d20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
35d30 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
35d40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
35d50 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
35d60 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
35d70 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
35d80 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
35d90 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
35da0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
35db0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
35dc0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
35dd0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
35de0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35df0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35e00 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35e10 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35e20 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
35e30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35e40 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35e50 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
35e60 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35e70 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35e80 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
35e90 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
35ea0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
35eb0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
35ec0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
35ed0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35ee0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
35ef0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
35f00 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
35f10 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
35f20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
35f30 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
35f40 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
35f50 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
35f60 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
35f70 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35f80 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
35f90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
35fa0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
35fb0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
35fc0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
35fd0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
35fe0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
35ff0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36000 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
36010 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36020 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36030 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
36040 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36050 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
36060 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
36070 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
36080 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36090 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
360a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
360b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
360c0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
360d0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
360e0 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
360f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
36100 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36110 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
36120 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
36130 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
36140 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
36150 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
36160 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36170 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
36180 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
36190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
361a0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
361b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
361c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
361d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
361e0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
361f0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
36200 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
36210 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
36220 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53  E_API sqlite3 *S
36230 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36240 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
36250 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
36260 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
36270 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
36280 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
36290 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
362a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
362b0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
362c0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
362d0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
362e0 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
362f0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
36300 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
36310 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
36320 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
36330 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
36340 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
36350 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
36360 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
36370 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
36380 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
36390 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
363a0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
363b0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
363c0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
363d0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
363e0 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
363f0 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
36400 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
36410 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
36420 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
36430 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
36440 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
36450 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
36460 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
36470 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
36480 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
36490 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
364a0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
364b0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
364c0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
364d0 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
364e0 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
364f0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
36500 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
36510 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
36520 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
36530 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
36540 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
36550 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
36560 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
36570 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
36580 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
36590 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
365a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
365b0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
365c0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
365d0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
365e0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
365f0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
36600 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
36610 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
36620 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
36630 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
36640 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
36650 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
36660 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
36670 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
36680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36690 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
366a0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
366b0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
366c0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
366d0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
366e0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
366f0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36700 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
36710 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
36720 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
36730 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
36740 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
36750 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
36760 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36770 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
36780 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
36790 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
367a0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
367b0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
367c0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
367d0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
367e0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
367f0 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
36800 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
36810 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
36820 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
36830 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
36840 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
36850 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
36860 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
36870 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
36880 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
36890 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
368a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
368b0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
368c0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
368d0 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
368e0 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
368f0 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
36900 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
36910 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
36920 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
36930 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
36940 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
36950 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
36960 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
36970 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
36980 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
36990 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
369a0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
369b0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
369c0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
369d0 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
369e0 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
369f0 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
36a00 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
36a10 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
36a20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
36a30 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
36a40 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
36a50 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36a60 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
36a70 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
36a80 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
36a90 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
36aa0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
36ab0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
36ac0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36ad0 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
36ae0 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
36af0 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
36b00 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
36b10 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
36b20 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
36b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
36b40 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
36b50 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36b60 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
36b70 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
36b80 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
36b90 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
36ba0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
36bb0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
36bc0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
36bd0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
36be0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
36bf0 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
36c00 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
36c10 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
36c20 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
36c30 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
36c40 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
36c50 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
36c60 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
36c70 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
36c80 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
36c90 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
36ca0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36cb0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
36cc0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
36cd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
36ce0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
36cf0 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
36d00 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36d10 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
36d20 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36d30 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
36d40 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
36d50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74  CALL sqlite3_set
36d60 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
36d70 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
36d80 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
36d90 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
36da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
36db0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
36dc0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
36dd0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
36de0 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
36df0 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
36e00 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
36e10 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
36e20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
36e30 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
36e40 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36e50 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
36e60 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
36e70 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
36e80 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
36e90 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
36ea0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
36eb0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
36ec0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
36ed0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
36ee0 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
36ef0 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
36f00 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
36f10 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
36f20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
36f30 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
36f40 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
36f50 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
36f60 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
36f70 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
36f80 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
36f90 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
36fa0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
36fb0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
36fc0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
36fd0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
36fe0 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
36ff0 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
37000 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
37010 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
37020 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
37030 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
37040 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
37050 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
37060 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
37070 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
37080 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
37090 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
370a0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
370b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
370c0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
370d0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
370e0 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ion.** METHOD: s
370f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37100 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
37110 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
37120 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
37130 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
37140 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
37150 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
37160 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
37170 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
37180 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
37190 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
371a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
371b0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
371c0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
371d0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
371e0 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
371f0 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
37200 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
37210 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
37220 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
37230 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
37240 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
37250 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
37260 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
37270 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
37280 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
37290 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
372a0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
372b0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
372c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
372d0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
372e0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
372f0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
37300 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37310 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37320 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
37330 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
37340 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
37350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
37360 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
37370 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
37380 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
37390 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
373a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
373b0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c  sult_zeroblob(C,
373c0 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  N) and sqlite3_r
373d0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34  esult_zeroblob64
373e0 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61  (C,N).** interfa
373f0 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
37400 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  lt of the applic
37410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37420 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
37430 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
37440 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73  g all zero bytes
37450 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
37460 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  size..**.** ^The
37470 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37480 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
37490 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
374a0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
374b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
374c0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
374d0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
374e0 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
374f0 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
37500 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37510 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37520 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37530 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37540 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
37550 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
37560 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
37570 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
37580 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
37590 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
375a0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
375b0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
375c0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
375d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
375e0 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
375f0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37600 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
37610 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
37620 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
37630 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37640 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
37650 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
37660 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37670 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
37680 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
37690 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
376a0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
376b0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
376c0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
376d0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
376e0 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
376f0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37700 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37710 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37720 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37730 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37740 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37750 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37760 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
37770 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
37780 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37790 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
377a0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
377b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
377c0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
377d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
377e0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
377f0 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
37800 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
37810 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
37820 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37830 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37840 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37850 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37860 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37870 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37880 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37890 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
378a0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
378b0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
378c0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
378d0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
378e0 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
378f0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
37900 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
37910 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
37920 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37930 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37940 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37950 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37960 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37970 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37980 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37990 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
379a0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
379b0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
379c0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
379d0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
379e0 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
379f0 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
37a00 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
37a10 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
37a20 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37a30 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37a40 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37a50 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37a60 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37a70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37a80 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37a90 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37aa0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37ab0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37ac0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37ad0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
37ae0 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
37af0 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
37b00 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37b10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37b20 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37b30 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37b40 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37b50 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37b60 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37b70 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37b80 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37b90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37ba0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37bb0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37bc0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37bd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37be0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37bf0 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
37c00 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
37c10 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
37c20 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37c30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37c40 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37c50 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37c60 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37c70 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37c80 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37c90 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
37ca0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
37cb0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
37cc0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
37cd0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37ce0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37cf0 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
37d00 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37d10 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37d20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37d30 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37d40 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
37d50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37d60 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
37d70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d80 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
37d90 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37da0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
37db0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37dc0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
37dd0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
37de0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
37df0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37e00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37e10 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
37e20 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
37e30 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
37e40 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37e50 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
37e60 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
37e70 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
37e80 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
37e90 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20  tively..** ^The 
37ea0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37eb0 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  ext64() interfac
37ec0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
37ed0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a  n value of an.**
37ee0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37ef0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37f00 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e   be a text strin
37f10 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67  g in an encoding
37f20 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79  .** specified by
37f30 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20   the fifth (and 
37f40 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c  last) parameter,
37f50 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f   which must be o
37f60 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45  ne.** of [SQLITE
37f70 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
37f80 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
37f90 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
37fa0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a  LITE_UTF16LE]..*
37fb0 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
37fc0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
37fd0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
37fe0 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
37ff0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
38000 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
38010 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
38020 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
38030 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
38040 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
38050 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
38060 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
38070 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
38080 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
38090 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
380a0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
380b0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
380c0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
380d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
380e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
380f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38100 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
38110 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
38120 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
38130 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
38140 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
38150 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
38160 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
38170 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
38180 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
38190 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
381a0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
381b0 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
381c0 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
381d0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
381e0 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
381f0 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
38200 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
38210 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
38220 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
38230 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
38240 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
38250 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
38260 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
38270 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
38280 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
38290 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
382a0 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
382b0 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
382c0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
382d0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
382e0 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
382f0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
38300 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
38310 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
38320 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
38330 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
38340 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
38350 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
38360 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
38370 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
38380 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
38390 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
383a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
383b0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
383c0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
383d0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
383e0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
383f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
38400 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
38410 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
38420 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
38430 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
38440 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
38450 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
38460 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
38470 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
38480 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
38490 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
384a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
384b0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
384c0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
384d0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
384e0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
384f0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
38500 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
38510 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
38520 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
38530 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
38540 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
38550 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
38560 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
38570 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
38580 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
38590 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
385a0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
385b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
385c0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
385d0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
385e0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
385f0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
38600 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
38610 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
38620 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
38630 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
38640 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
38650 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
38660 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
38670 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
38680 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
38690 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
386a0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
386b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
386c0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
386d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
386e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
386f0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
38700 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
38710 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
38720 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62 79  ect specified by
38730 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38740 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  er.  ^The.** sql
38750 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
38760 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61  e() interface ma
38770 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
38780 65 20 5b 73 71 6c 69 74 65 33