System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 7157e90e5f10494a6067076135f5ed50ce81d007:


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 38 2e 31 32 22 0a 23 64       "3.8.12".#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 30 38  SION_NUMBER 3008
10d0: 30 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  012.#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 30 39 2d 31 31 20 31 38    "2015-09-11 18
1100: 3a 30 35 3a 30 31 20 62 66 63 37 62 38 34 62 37  :05:01 bfc7b84b7
1110: 36 36 38 36 30 64 32 65 34 31 30 37 30 32 62 61  66860d2e410702ba
1120: 37 63 31 31 36 36 64 37 33 32 38 33 30 39 61 22  7c1166d7328309a"
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 69  ader, and thus i
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 69 6e  lication must in
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 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
5700: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
5710: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
5720: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5740: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5750: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5780: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
57a0: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
57c0: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
57e0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
57f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5800: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
5810: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5820: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
5830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5840: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5850: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5860: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5870: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5880: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5890: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
58a0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
58b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58c0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
58d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
58e0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5900: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5910: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5920: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
5930: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5940: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5950: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5960: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5970: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5980: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5990: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
59a0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
59b0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
59c0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
59d0: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
59e0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
59f0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
5a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
5a10: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
5a20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
5a30: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5a40: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a50: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5a60: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a70: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5a80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a90: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5aa0: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5ab0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5ac0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ad0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
5ae0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
5af0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5b00: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5b10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b20: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
5b30: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b40: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b60: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5b70: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b80: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5ba0: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5bb0: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5bc0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5bd0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5be0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
5bf0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
5c00: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5c10: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
5c20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c30: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5c40: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c50: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5c60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c70: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5c80: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c90: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5ca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5cb0: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5cc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5cd0: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5ce0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cf0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5d00: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5d10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
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 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5d50: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5d60: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5d70: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5d80: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5d90: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5da0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5db0: 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20  ITE_AUTH_USER   
5dc0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5dd0: 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38  ITE_AUTH | (1<<8
5de0: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5df0: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5e00: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5e10: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5e20: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5e30: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
5e40: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
5e50: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
5e60: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
5e70: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
5e80: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
5e90: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5ea0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
5eb0: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
5ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5ed0: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
5ee0: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
5ef0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f00: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f20: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
5f30: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
5f40: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5f50: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5f60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5f70: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
5f80: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
5f90: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
5fa0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
5fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
5fc0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
5fd0: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
5fe0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
5ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6000: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
6010: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
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 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
6050: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
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 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
6090: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
60a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
60b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
60c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
60d0: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
60e0: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
60f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6100: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6120: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
6130: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
6140: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
6150: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6160: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
6170: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
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 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
61b0: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
61f0: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
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 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
6230: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
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 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
6270: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
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 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
62b0: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
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 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
62f0: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
6300: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6310: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6330: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
6340: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
6350: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6360: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6380: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
6390: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
63a0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
63b0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
63c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
63d0: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
63e0: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
63f0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
6400: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
6410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
6420: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
6430: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
6440: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
6450: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
6460: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6470: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
6480: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
6490: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
64a0: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
64b0: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
64c0: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
64d0: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
64e0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
64f0: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
6500: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
6510: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
6520: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
6530: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
6540: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
6550: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
6560: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
6570: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
6580: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
6590: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
65a0: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
65b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
65c0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
65d0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
65e0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
65f0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
6600: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
6610: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6620: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
6630: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
6640: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
6650: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
6660: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
6670: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
6680: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
6690: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
66a0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
66b0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
66c0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
66d0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
66e0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
66f0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6700: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
6710: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
6720: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
6730: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
6740: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
6750: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
6760: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
6770: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6780: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
6790: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
67a0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
67b0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
67c0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
67d0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
67e0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
67f0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6800: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
6810: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
6820: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
6830: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
6840: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
6850: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
6860: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
6870: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
6880: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
6890: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
68a0: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
68b0: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
68c0: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
68d0: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
68e0: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
68f0: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
6900: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
6910: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
6920: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
6930: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
6940: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
6950: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
6960: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
6970: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
6980: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
6990: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
69a0: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
69b0: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
69c0: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
69d0: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
69e0: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
69f0: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
6a00: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
6a10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6a20: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
6a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6a40: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
6a50: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6a60: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
6a70: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
6a80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6a90: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
6aa0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6ab0: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
6ac0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ad0: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
6ae0: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
6af0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6b00: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
6b10: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b20: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
6b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b40: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
6b50: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
6b60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b70: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
6b80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b90: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
6ba0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
6bb0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6bc0: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
6bd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6be0: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
6bf0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6c00: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c10: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6c20: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
6c30: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
6c40: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6c50: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
6c60: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
6c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c80: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
6c90: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
6ca0: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
6cb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6cc0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6cd0: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
6ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6cf0: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
6d00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d10: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
6d20: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
6d30: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
6d40: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
6d50: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
6d60: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
6d70: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
6d80: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
6d90: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
6da0: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
6db0: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
6dc0: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
6dd0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
6de0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6df0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
6e00: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
6e10: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
6e20: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
6e30: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
6e40: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
6e50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e60: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
6e70: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
6e80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
6e90: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
6ea0: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
6eb0: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
6ec0: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
6ed0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
6ee0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
6ef0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
6f00: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
6f10: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
6f20: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
6f30: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6f40: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6f50: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
6f60: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
6f70: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
6f80: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
6f90: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
6fa0: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
6fb0: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
6fc0: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
6fd0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
6fe0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
6ff0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
7000: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
7010: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
7020: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
7030: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
7040: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
7050: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
7060: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
7070: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
7080: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
7090: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
70a0: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
70b0: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
70c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
70d0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
70e0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
70f0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
7100: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7110: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7120: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
7130: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
7140: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
7150: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
7160: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
7170: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
7180: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
7190: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
71a0: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
71b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
71c0: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
71d0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
71e0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
71f0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
7200: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
7210: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
7220: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
7230: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
7240: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
7250: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
7260: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
7270: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
7280: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
7290: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
72a0: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
72b0: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
72c0: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
72d0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
72e0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
72f0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
7300: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
7310: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
7320: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
7330: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
7340: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
7350: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
7360: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
7370: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
7380: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
7390: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
73a0: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
73b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
73c0: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
73d0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
73e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
73f0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
7400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7410: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
7420: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
7430: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
7440: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
7450: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
7460: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
7470: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
7480: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
7490: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
74a0: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
74b0: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
74c0: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
74d0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
74e0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
74f0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
7500: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
7510: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
7520: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
7530: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
7540: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
7550: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
7560: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
7570: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7580: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
7590: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
75a0: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
75b0: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
75c0: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
75d0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
75e0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
75f0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
7600: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
7610: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
7620: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
7630: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
7640: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
7650: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
7660: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
7670: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
7680: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
7690: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
76a0: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
76b0: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
76c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
76d0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
76e0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
76f0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
7700: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
7710: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
7720: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
7730: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
7740: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
7750: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7760: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
7770: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
7780: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
7790: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
77a0: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
77b0: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
77c0: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
77d0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
77e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
77f0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
7800: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7810: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7820: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
7830: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
7840: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
7850: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
7860: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
7870: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
7880: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
7890: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
78a0: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
78b0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
78c0: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
78d0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
78e0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
78f0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
7900: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
7910: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
7920: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
7930: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
7940: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
7950: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
7960: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
7970: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
7980: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
7990: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
79a0: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
79b0: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
79c0: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
79d0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
79e0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
79f0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
7a00: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
7a10: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
7a20: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
7a30: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
7a40: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
7a50: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
7a60: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
7a70: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
7a80: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
7a90: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
7aa0: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
7ab0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
7ac0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
7ad0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
7ae0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
7af0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
7b00: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
7b10: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7b20: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
7b30: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
7b40: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b50: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7b60: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
7b70: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
7b80: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
7b90: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7ba0: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
7bb0: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
7bc0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
7bd0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
7be0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
7bf0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
7c00: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
7c10: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
7c20: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
7c30: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
7c40: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
7c50: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
7c60: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
7c70: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
7c80: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
7c90: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
7ca0: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
7cb0: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
7cc0: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
7cd0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
7ce0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
7cf0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
7d00: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
7d10: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
7d20: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
7d30: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
7d40: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
7d50: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
7d60: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
7d70: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
7d80: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
7d90: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
7da0: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
7db0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
7dc0: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
7dd0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
7de0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
7df0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
7e00: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
7e10: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
7e20: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
7e30: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
7e40: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
7e50: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
7e60: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
7e70: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
7e80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
7e90: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
7ea0: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
7eb0: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
7ec0: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
7ed0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
7ee0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
7ef0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
7f00: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
7f10: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
7f20: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
7f30: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
7f40: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
7f50: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
7f60: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
7f70: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
7f80: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
7f90: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
7fa0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
7fb0: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
7fc0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7fd0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7fe0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7ff0: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
8000: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
8010: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
8020: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
8030: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
8040: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
8050: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
8060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
8070: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
8080: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
8090: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
80a0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
80b0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
80c0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
80d0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
80e0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
80f0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
8100: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
8110: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
8120: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
8130: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
8140: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
8150: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
8160: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8170: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8180: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8190: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
81a0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
81b0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
81c0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
81d0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
81e0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
81f0: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
8200: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
8210: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8220: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
8230: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8240: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
8250: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8260: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8270: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8280: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
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 34 4b 5d 0a  IOCAP_ATOMIC4K].
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 38 4b 5d 0a  IOCAP_ATOMIC8K].
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 31 36 4b 5d  IOCAP_ATOMIC16K]
82f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8300: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
8310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
8320: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
8330: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
8340: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
8350: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
8360: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8370: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8380: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8390: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
83a0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
83b0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
83c0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
83d0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
83e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
83f0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8400: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8410: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8420: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8430: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8440: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8450: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8460: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8470: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8480: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8490: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
84a0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
84b0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
84c0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84d0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
84e0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
84f0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8500: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8510: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8520: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8530: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8540: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8550: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8560: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8570: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8580: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8590: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
85a0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
85b0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
85c0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
85d0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
85e0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
85f0: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8600: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
8610: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
8620: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
8630: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
8640: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
8650: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
8660: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8670: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8680: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8690: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
86a0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
86b0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
86c0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
86d0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
86e0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
86f0: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8700: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
8710: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8720: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
8730: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
8740: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
8750: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8760: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8770: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8780: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8790: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
87a0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
87c0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
87d0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
87e0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
87f0: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8800: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
8810: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
8820: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
8830: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8840: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
8850: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
8860: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8870: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8880: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8890: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
88a0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
88b0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
88c0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
88d0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
88e0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
88f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8900: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
8910: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
8920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8930: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
8940: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
8950: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
8960: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8970: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8980: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8990: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
89a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
89b0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
89c0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
89d0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
89e0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
89f0: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8a00: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
8a10: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
8a40: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
8a50: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
8a60: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8a80: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8a90: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8aa0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8ab0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8ac0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8ad0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8ae0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8af0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8b00: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
8b10: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
8b20: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
8b30: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8b40: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8b50: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
8b60: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8b70: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8b80: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8b90: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8ba0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8bb0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8bc0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8bd0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8be0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8bf0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
8c00: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
8c10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
8c20: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
8c30: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
8c40: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
8c50: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
8c60: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
8c70: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
8c80: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
8c90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
8ca0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
8cb0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8cc0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
8cd0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
8ce0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8cf0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
8d00: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
8d10: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8d20: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8d30: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8d40: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8d50: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8d60: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8d70: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8d80: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8d90: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8da0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8db0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8dc0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8dd0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8de0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8df0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8e00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8e10: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8e20: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8e30: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8e40: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8e50: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8e60: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8e70: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
8e80: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
8e90: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
8ea0: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
8eb0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
8ec0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
8ed0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
8ee0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
8ef0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
8f00: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
8f10: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
8f20: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
8f30: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
8f40: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
8f50: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
8f60: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
8f70: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
8f80: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
8f90: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
8fa0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
8fb0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
8fc0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
8fd0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
8fe0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
8ff0: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
9000: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
9010: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
9020: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
9030: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
9040: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
9050: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
9060: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
9070: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9080: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
9090: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
90b0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
90c0: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
90d0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
90e0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
90f0: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
9100: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
9110: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
9120: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
9130: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
9140: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
9150: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9160: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
9170: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
9180: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
9190: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
91a0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
91b0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
91c0: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
91d0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
91e0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
91f0: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
9200: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
9210: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
9220: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
9230: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
9240: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
9250: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
9260: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
9270: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9280: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9290: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
92a0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
92b0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
92c0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
92d0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
92e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92f0: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9300: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
9310: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
9320: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
9330: 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  See the [sqlite3
9340: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
9350: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
9360: 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
9370: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
9380: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9390: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
93a0: 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67  TED]].** No long
93b0: 65 72 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a  er in use..**.**
93c0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
93d0: 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68  NTL_SYNC]].** Th
93e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
93f0: 53 59 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20  SYNC] opcode is 
9400: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
9410: 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61  ally by SQLite a
9420: 6e 64 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68  nd.** sent to th
9430: 65 20 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c  e VFS immediatel
9440: 79 20 62 65 66 6f 72 65 20 74 68 65 20 78 53 79  y before the xSy
9450: 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  nc method is inv
9460: 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74  oked on a.** dat
9470: 61 62 61 73 65 20 66 69 6c 65 20 64 65 73 63 72  abase file descr
9480: 69 70 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68  iptor. Or, if th
9490: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
94a0: 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a  s not invoked .*
94b0: 2a 20 62 65 63 61 75 73 65 20 74 68 65 20 75 73  * because the us
94c0: 65 72 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65  er has configure
94d0: 64 20 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a  d SQLite with .*
94e0: 2a 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72  * [PRAGMA synchr
94f0: 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73  onous | PRAGMA s
9500: 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20  ynchronous=OFF] 
9510: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e  it is invoked in
9520: 20 70 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68   place .** of th
9530: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20  e xSync method. 
9540: 49 6e 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74  In most cases, t
9550: 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
9560: 65 6e 74 20 70 61 73 73 65 64 20 77 69 74 68 0a  ent passed with.
9570: 2a 2a 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  ** this file-con
9580: 74 72 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f  trol is NULL. Ho
9590: 77 65 76 65 72 2c 20 69 66 20 74 68 65 20 64 61  wever, if the da
95a0: 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 62  tabase file is b
95b0: 65 69 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61  eing synced.** a
95c0: 73 20 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74  s part of a mult
95d0: 69 2d 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69  i-database commi
95e0: 74 2c 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  t, the argument 
95f0: 70 6f 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d  points to a nul-
9600: 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
9610: 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ring containing 
9620: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73  the transactions
9630: 20 6d 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20   master-journal 
9640: 66 69 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73  file name. VFSes
9650: 20 74 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74   that .** do not
9660: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9670: 6c 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  l should silentl
9680: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
9690: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
96a0: 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ns .** should no
96b0: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
96c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
96d0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
96e0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
96f0: 20 0a 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65   .** disrupt the
9700: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
9710: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
9720: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
9730: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
9740: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9750: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9760: 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  WO]].** The [SQL
9770: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
9780: 5f 50 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64  _PHASETWO] opcod
9790: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
97a0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
97b0: 69 74 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20  ite.** and sent 
97c0: 74 6f 20 74 68 65 20 56 46 53 20 61 66 74 65 72  to the VFS after
97d0: 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68   a transaction h
97e0: 61 73 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65  as been committe
97f0: 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a  d immediately.**
9800: 20 62 75 74 20 62 65 66 6f 72 65 20 74 68 65 20   but before the 
9810: 64 61 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f  database is unlo
9820: 63 6b 65 64 2e 20 56 46 53 65 73 20 74 68 61 74  cked. VFSes that
9830: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
9840: 73 20 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75  s signal.** shou
9850: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
9860: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
9870: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
9880: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20  uld not call.** 
9890: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
98a0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
98b0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
98c0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
98d0: 74 20 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74  t the .** operat
98e0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
98f0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9900: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9910: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9920: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9930: 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20  2_AV_RETRY]].** 
9940: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
9960: 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  Y] opcode is use
9970: 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61  d to configure a
9980: 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72  utomatic.** retr
9990: 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74  y counts and int
99a0: 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61  ervals for certa
99b0: 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72  in disk I/O oper
99c0: 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a  ations for the.*
99d0: 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20  * windows [VFS] 
99e0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76  in order to prov
99f0: 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69  ide robustness i
9a00: 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  n the presence o
9a10: 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20  f.** anti-virus 
9a20: 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65  programs.  By de
9a30: 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f  fault, the windo
9a40: 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72  ws VFS will retr
9a50: 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20  y file read,.** 
9a60: 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20  file write, and 
9a70: 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72  file delete oper
9a80: 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20  ations up to 10 
9a90: 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65  times, with a de
9aa0: 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c  lay.** of 25 mil
9ab0: 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65  liseconds before
9ac0: 20 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79   the first retry
9ad0: 20 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65   and with the de
9ae0: 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a  lay increasing.*
9af0: 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e  * by an addition
9b00: 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  al 25 millisecon
9b10: 64 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62  ds with each sub
9b20: 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20  sequent retry.  
9b30: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  This.** opcode a
9b40: 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20  llows these two 
9b50: 76 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69  values (10 retri
9b60: 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73  es and 25 millis
9b70: 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29  econds of delay)
9b80: 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74  .** to be adjust
9b90: 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20  ed.  The values 
9ba0: 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20  are changed for 
9bb0: 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e  all database con
9bc0: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  nections.** with
9bd0: 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63  in the same proc
9be0: 65 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ess.  The argume
9bf0: 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
9c00: 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74  to an array of t
9c10: 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77  wo.** integers w
9c20: 68 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69  here the first i
9c30: 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77  nteger i the new
9c40: 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64   retry count and
9c50: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69   the second.** i
9c60: 6e 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65  nteger is the de
9c70: 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20  lay.  If either 
9c80: 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74  integer is negat
9c90: 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65  ive, then the se
9ca0: 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20  tting.** is not 
9cb0: 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74  changed but inst
9cc0: 65 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61  ead the prior va
9cd0: 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74  lue of that sett
9ce0: 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  ing is written.*
9cf0: 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79  * into the array
9d00: 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67   entry, allowing
9d10: 20 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74   the current ret
9d20: 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62  ry settings to b
9d30: 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65  e.** interrogate
9d40: 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20  d.  The zDbName 
9d50: 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e  parameter is ign
9d60: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ored..**.** <li>
9d70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9d80: 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20  ERSIST_WAL]].** 
9d90: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9da0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20  TL_PERSIST_WAL] 
9db0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
9dc0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
9dd0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
9de0: 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68   [WAL | Write Ah
9df0: 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67  ead Log] setting
9e00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
9e10: 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20  he auxiliary.** 
9e20: 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20  write ahead log 
9e30: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
9e40: 79 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72  y files used for
9e50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e   transaction con
9e60: 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f  trol.** are auto
9e70: 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65  matically delete
9e80: 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73  d when the lates
9e90: 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  t connection to 
9ea0: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
9eb0: 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67  closes.  Setting
9ec0: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
9ed0: 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73  mode causes thos
9ee0: 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69  e files to persi
9ef0: 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73  st after.** clos
9f00: 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74  e.  Persisting t
9f10: 68 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66  he files is usef
9f20: 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72  ul when other pr
9f30: 6f 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20  ocesses that do 
9f40: 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74  not.** have writ
9f50: 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20  e permission on 
9f60: 74 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f  the directory co
9f70: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74  ntaining the dat
9f80: 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a  abase file want.
9f90: 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64  ** to read the d
9fa0: 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73  atabase file, as
9fb0: 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61   the WAL and sha
9fc0: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9fd0: 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69   must exist.** i
9fe0: 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20  n order for the 
9ff0: 64 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  database to be r
a000: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f  eadable.  The fo
a010: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a020: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a030: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a040: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a050: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a060: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a070: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a080: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a090: 20 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20   persistent WAL 
a0a0: 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61  mode or 1 to ena
a0b0: 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  ble persistent.*
a0c0: 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20  * WAL mode.  If 
a0d0: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a0e0: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a0f0: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a100: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41  he current.** WA
a110: 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65  L persistence se
a120: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
a130: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a140: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
a150: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a160: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a170: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a180: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
a190: 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20  to set or query 
a1a0: 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e  the.** persisten
a1b0: 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65  t "powersafe-ove
a1c0: 72 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57  rwrite" or "PSOW
a1d0: 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20  " setting.  The 
a1e0: 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20  PSOW setting.** 
a1f0: 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b  determines the [
a200: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
a210: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
a220: 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20  ] bit of the.** 
a230: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
a240: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20  istics methods. 
a250: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
a260: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
a270: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a280: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
a290: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
a2a0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
a2b0: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
a2c0: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
a2d0: 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  isable zero-dama
a2e0: 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20  ge mode or 1 to 
a2f0: 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61  enable zero-dama
a300: 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20  ge.** mode.  If 
a310: 74 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d  the integer is -
a320: 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76  1, then it is ov
a330: 65 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74  erwritten with t
a340: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65  he current.** ze
a350: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73  ro-damage mode s
a360: 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  etting..**.** <l
a370: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a380: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
a390: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a3a0: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70  TL_OVERWRITE] op
a3b0: 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  code is invoked 
a3c0: 62 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20  by SQLite after 
a3d0: 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69  opening.** a wri
a3e0: 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74  te transaction t
a3f0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c  o indicate that,
a400: 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f   unless it is ro
a410: 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f  lled back for so
a420: 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68  me.** reason, th
a430: 65 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73  e entire databas
a440: 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f  e file will be o
a450: 76 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68  verwritten by th
a460: 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72  e current .** tr
a470: 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20  ansaction. This 
a480: 69 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55  is used by VACUU
a490: 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  M operations..**
a4a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a4b0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d  _FCNTL_VFSNAME]]
a4c0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a4d0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20  _FCNTL_VFSNAME] 
a4e0: 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73  opcode can be us
a4f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
a500: 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c   names of.** all
a510: 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20   [VFSes] in the 
a520: 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20  VFS stack.  The 
a530: 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c  names are of all
a540: 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74   VFS shims and t
a550: 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74  he.** final bott
a560: 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65  om-level VFS are
a570: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
a580: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
a590: 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
a5a0: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68  malloc()] and th
a5b0: 65 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72  e result is stor
a5c0: 65 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20  ed in the char* 
a5d0: 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74  variable.** that
a5e0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
a5f0: 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65  meter of [sqlite
a600: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a610: 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20  ] points to..** 
a620: 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65  The caller is re
a630: 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72  sponsible for fr
a640: 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79  eeing the memory
a650: 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20   when done.  As 
a660: 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65  with.** all file
a670: 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73  -control actions
a680: 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75  , there is no gu
a690: 61 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69  arantee that thi
a6a0: 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a  s will actually.
a6b0: 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20  ** do anything. 
a6c0: 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20   Callers should 
a6d0: 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63  initialize the c
a6e0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f  har* variable to
a6f0: 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
a700: 65 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20  er in case this 
a710: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
a720: 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e  not implemented.
a730: 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74    This file-cont
a740: 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64  rol.** is intend
a750: 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69  ed for diagnosti
a760: 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  c use only..**.*
a770: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a780: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
a790: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
a7a0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
a7b0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
a7c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a7d0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
a7e0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
a7f0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
a800: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
a810: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
a820: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
a830: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
a840: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
a850: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
a860: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
a870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a880: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a890: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
a8a0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
a8b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
a8c0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
a8d0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
a8e0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
a8f0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
a900: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
a910: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
a920: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
a930: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
a940: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
a950: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
a960: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
a970: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
a980: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a990: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a9a0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
a9b0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
a9c0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
a9d0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
a9e0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
a9f0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
aa00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
aa10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
aa20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
aa30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
aa40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
aa50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
aa60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
aa70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
aa80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
aa90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
aaa0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
aab0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
aac0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
aad0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
aae0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
aaf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
ab00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
ab10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ab30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ab40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ab50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ab60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ab70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ab80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ab90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
aba0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
abb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
abc0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
abd0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
abe0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
abf0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
ac00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
ac10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
ac20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
ac30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
ac40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ac50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ac60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
ac70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
ac80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
ac90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
aca0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
acb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
acc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
acd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
ace0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
acf0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
ad00: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
ad10: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
ad20: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
ad30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ad40: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
ad50: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
ad60: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
ad70: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
ad80: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
ad90: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
ada0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
adb0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
adc0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
add0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ade0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
adf0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
ae00: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
ae10: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
ae20: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
ae30: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
ae40: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ae50: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
ae60: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
ae70: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
ae80: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
ae90: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
aea0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
aeb0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
aec0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
aed0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
aee0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
aef0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
af00: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
af10: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
af20: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
af30: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
af40: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
af50: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
af60: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
af70: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
af80: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
af90: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
afa0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
afb0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
afc0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
afd0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
afe0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
aff0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b000: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b010: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b020: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b030: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b040: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b050: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b060: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b070: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b080: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b090: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b0a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b0b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b0c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b0e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b0f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b100: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b110: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b120: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b130: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b140: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b150: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b160: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b170: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b180: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b190: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b1a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b1b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b1c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b1d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b1e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b1f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b200: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b210: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b220: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b230: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b240: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b250: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b260: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b270: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b280: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b290: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b2a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b2b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b2c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b2d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b2e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b2f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b300: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b310: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b320: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b330: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b340: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b350: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b360: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b370: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b380: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b390: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b3a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b3b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b3c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b3d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b3e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b3f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b400: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b410: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b420: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b430: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b440: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b450: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b460: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b470: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b480: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b490: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b4a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b4b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b4c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b4d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b4e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b4f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b500: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b510: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b520: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b530: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b540: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b550: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b560: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b570: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b580: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b590: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b5a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b5b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b5c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b5d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b5e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b5f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b600: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b610: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b620: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b630: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b640: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b650: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b660: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b670: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b680: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b690: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b6a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b6b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b6c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b6d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b6e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b6f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
b700: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
b710: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
b720: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
b730: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
b740: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
b750: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
b760: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
b770: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
b780: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
b790: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
b7a0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
b7b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b7c0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
b7d0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
b7e0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
b7f0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
b800: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b810: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b820: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b830: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b840: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
b850: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
b860: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
b870: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
b880: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
b890: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
b8a0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
b8b0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
b8c0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
b8d0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
b8e0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
b8f0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
b900: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b910: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
b920: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b930: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
b940: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
b950: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
b960: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
b970: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
b980: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
b990: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
b9a0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
b9b0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
b9c0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
b9d0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
b9e0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
b9f0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
ba00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
ba10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
ba20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
ba30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
ba40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
ba50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
ba60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
ba70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
ba80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ba90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
baa0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bab0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bac0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bad0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bae0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
baf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
bb00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
bb10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
bb20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bb30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
bb40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
bb50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
bb60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
bb70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
bb80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
bb90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bba0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
bbb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bbc0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bbd0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bbe0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bbf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bc10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bc20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bc30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bc50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bc60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bc70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bc80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bc90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bca0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bcb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bcc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bcd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bce0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bcf0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
bd00: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
bd10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
bd20: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
bd30: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
bd40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
bd50: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
bd60: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
bd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
bd80: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
bd90: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
bda0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bdb0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
bdc0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
bdd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
bde0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
bdf0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
be00: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
be10: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
be20: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
be30: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
be40: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
be50: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
be60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
be80: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
be90: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
bea0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
beb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bec0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bed0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bee0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bef0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bf00: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
bf10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf20: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bf30: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bf40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf50: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bf60: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bf70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf80: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bf90: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bfa0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfb0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bfc0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bfd0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bfe0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bff0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c000: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c010: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c020: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c030: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c040: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c050: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c060: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c070: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c080: 20 20 20 20 32 36 0a 0a 2f 2a 20 64 65 70 72 65      26../* depre
c090: 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23  cated names */.#
c0a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
c0b0: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
c0c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54       SQLITE_FCNT
c0d0: 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_GET_LOCKPROXYF
c0e0: 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  ILE.#define SQLI
c0f0: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
c100: 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45  FILE      SQLITE
c110: 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50  _FCNTL_SET_LOCKP
c120: 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65  ROXYFILE.#define
c130: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
c140: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53  NO             S
c150: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54  QLITE_FCNTL_LAST
c160: 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  _ERRNO.../*.** C
c170: 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48  API3REF: Mutex H
c180: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  andle.**.** The 
c190: 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74  mutex module wit
c1a0: 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e  hin SQLite defin
c1b0: 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  es [sqlite3_mute
c1c0: 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61  x] to be an.** a
c1d0: 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72  bstract type for
c1e0: 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e   a mutex object.
c1f0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72    The SQLite cor
c200: 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a  e never looks.**
c210: 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   at the internal
c220: 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
c230: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d  of an [sqlite3_m
c240: 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a  utex].  It only.
c250: 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f  ** deals with po
c260: 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73  inters to the [s
c270: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62  qlite3_mutex] ob
c280: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65  ject..**.** Mute
c290: 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20  xes are created 
c2a0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  using [sqlite3_m
c2b0: 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  utex_alloc()]..*
c2c0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
c2d0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73   sqlite3_mutex s
c2e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f  qlite3_mutex;../
c2f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
c300: 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65  S Interface Obje
c310: 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  ct.**.** An inst
c320: 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69  ance of the sqli
c330: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64  te3_vfs object d
c340: 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
c350: 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20  face between.** 
c360: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  the SQLite core 
c370: 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  and the underlyi
c380: 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ng operating sys
c390: 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a  tem.  The "vfs".
c3a0: 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f  ** in the name o
c3b0: 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61  f the object sta
c3c0: 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c  nds for "virtual
c3d0: 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20   file system".  
c3e0: 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20  See.** the [VFS 
c3f0: 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74  | VFS documentat
c400: 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72  ion] for further
c410: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
c420: 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66  .** The value of
c430: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
c440: 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79  eld is initially
c450: 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61   1 but may be la
c460: 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72  rger in.** futur
c470: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
c480: 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61  Lite.  Additiona
c490: 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20  l fields may be 
c4a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73  appended to this
c4b0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20  .** object when 
c4c0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c  the iVersion val
c4d0: 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e  ue is increased.
c4e0: 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20    Note that the 
c4f0: 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20  structure.** of 
c500: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
c510: 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69  object changes i
c520: 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  n the transactio
c530: 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c  n between.** SQL
c540: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
c550: 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20  9 and 3.6.0 and 
c560: 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e  yet the iVersion
c570: 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a   field was not.*
c580: 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a  * modified..**.*
c590: 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66  * The szOsFile f
c5a0: 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65  ield is the size
c5b0: 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73   of the subclass
c5c0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ed [sqlite3_file
c5d0: 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75  ].** structure u
c5e0: 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e  sed by this VFS.
c5f0: 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20    mxPathname is 
c600: 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  the maximum leng
c610: 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e  th of.** a pathn
c620: 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e  ame in this VFS.
c630: 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65  .**.** Registere
c640: 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  d sqlite3_vfs ob
c650: 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f  jects are kept o
c660: 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20  n a linked list 
c670: 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65  formed by.** the
c680: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20   pNext pointer. 
c690: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
c6a0: 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a  s_register()].**
c6b0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66   and [sqlite3_vf
c6c0: 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20  s_unregister()] 
c6d0: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67  interfaces manag
c6e0: 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69  e this list.** i
c6f0: 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20  n a thread-safe 
c700: 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  way.  The [sqlit
c710: 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69  e3_vfs_find()] i
c720: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72  nterface.** sear
c730: 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20  ches the list.  
c740: 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c  Neither the appl
c750: 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72  ication code nor
c760: 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c   the VFS.** impl
c770: 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c  ementation shoul
c780: 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20  d use the pNext 
c790: 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  pointer..**.** T
c7a0: 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69  he pNext field i
c7b0: 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64  s the only field
c7c0: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f   in the sqlite3_
c7d0: 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  vfs.** structure
c7e0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
c7f0: 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20  l ever modify.  
c800: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79  SQLite will only
c810: 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f   access.** or mo
c820: 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20  dify this field 
c830: 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20  while holding a 
c840: 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69  particular stati
c850: 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20  c mutex..** The 
c860: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c870: 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20  ld never modify 
c880: 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20  anything within 
c890: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
c8a0: 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74  ** object once t
c8b0: 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65  he object has be
c8c0: 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a  en registered..*
c8d0: 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66  *.** The zName f
c8e0: 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e  ield holds the n
c8f0: 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d  ame of the VFS m
c900: 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65  odule.  The name
c910: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71   must.** be uniq
c920: 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46  ue across all VF
c930: 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a  S modules..**.**
c940: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
c950: 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74  Open]].** ^SQLit
c960: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
c970: 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  t the zFilename 
c980: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c990: 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  en.** is either 
c9a0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f  a NULL pointer o
c9b0: 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  r string obtaine
c9c0: 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50  d.** from xFullP
c9d0: 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61  athname() with a
c9e0: 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69  n optional suffi
c9f0: 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  x added..** ^If 
ca00: 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65  a suffix is adde
ca10: 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61  d to the zFilena
ca20: 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74  me parameter, it
ca30: 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74   will.** consist
ca40: 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22   of a single "-"
ca50: 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f   character follo
ca60: 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74  wed by no more t
ca70: 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e  han.** 11 alphan
ca80: 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d  umeric and/or "-
ca90: 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  " characters..**
caa0: 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72   ^SQLite further
cab0: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
cac0: 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77  .** the string w
cad0: 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64  ill be valid and
cae0: 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c   unchanged until
caf0: 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20   xClose() is.** 
cb00: 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20  called. Because 
cb10: 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  of the previous 
cb20: 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65  sentence,.** the
cb30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
cb40: 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65  can safely store
cb50: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
cb60: 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66  e.** filename if
cb70: 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d   it needs to rem
cb80: 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61  ember the filena
cb90: 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  me for some reas
cba0: 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46  on..** If the zF
cbb0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
cbc0: 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20  r to xOpen is a 
cbd0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
cbe0: 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20  n xOpen.** must 
cbf0: 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74  invent its own t
cc00: 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f  emporary name fo
cc10: 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68  r the file.  ^Wh
cc20: 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78  enever the .** x
cc30: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
cc40: 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69  er is NULL it wi
cc50: 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63  ll also be the c
cc60: 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ase that the.** 
cc70: 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
cc80: 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51  will include [SQ
cc90: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cca0: 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20  ONCLOSE]..**.** 
ccb0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
ccc0: 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e  nt to xOpen() in
ccd0: 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20  cludes all bits 
cce0: 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c  set in.** the fl
ccf0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
cd00: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
cd10: 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c  ()].  Or if [sql
cd20: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
cd30: 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  or [sqlite3_open
cd40: 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74  16()] is used, t
cd50: 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64  hen flags includ
cd60: 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b  es at least.** [
cd70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
cd80: 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
cd90: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a  _OPEN_CREATE]. .
cda0: 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70  ** If xOpen() op
cdb0: 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d  ens a file read-
cdc0: 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74  only then it set
cdd0: 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a  s *pOutFlags to.
cde0: 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ** include [SQLI
cdf0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
ce00: 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69  ].  Other bits i
ce10: 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79  n *pOutFlags may
ce20: 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e   be set..**.** ^
ce30: 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73  (SQLite will als
ce40: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
ce50: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
ce60: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a   to the xOpen().
ce70: 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69  ** call, dependi
ce80: 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74  ng on the object
ce90: 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a   being opened:.*
cea0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ceb0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
cec0: 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  MAIN_DB].** <li>
ced0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
cee0: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  AIN_JOURNAL].** 
cef0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cf00: 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c  EN_TEMP_DB].** <
cf10: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cf20: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_TEMP_JOURNAL].
cf30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
cf40: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
cf50: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
cf60: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
cf70: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cf80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
cf90: 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  ER_JOURNAL].** <
cfa0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
cfb0: 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29  N_WAL].** </ul>)
cfc0: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65  ^.**.** The file
cfd0: 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74   I/O implementat
cfe0: 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20  ion can use the 
cff0: 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67  object type flag
d000: 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74  s to.** change t
d010: 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20  he way it deals 
d020: 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72  with files.  For
d030: 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
d040: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  lication.** that
d050: 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61   does not care a
d060: 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76  bout crash recov
d070: 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  ery or rollback 
d080: 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68  might make.** th
d090: 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72  e open of a jour
d0a0: 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70  nal file a no-op
d0b0: 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69  .  Writes to thi
d0c0: 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a  s journal would.
d0d0: 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70  ** also be no-op
d0e0: 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d  s, and any attem
d0f0: 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a  pt to read the j
d100: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74  ournal would ret
d110: 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  urn.** SQLITE_IO
d120: 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70  ERR.  Or the imp
d130: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68  lementation migh
d140: 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74  t recognize that
d150: 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66   a database.** f
d160: 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e  ile will be doin
d170: 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73  g page-aligned s
d180: 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20  ector reads and 
d190: 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64  writes in a rand
d1a0: 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20  om.** order and 
d1b0: 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73  set up its I/O s
d1c0: 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69  ubsystem accordi
d1d0: 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  ngly..**.** SQLi
d1e0: 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64  te might also ad
d1f0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
d200: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
d210: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
d220: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
d230: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
d240: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
d250: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d260: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
d270: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
d280: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d290: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20  _DELETEONCLOSE] 
d2a0: 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66  flag means the f
d2b0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ile should be.**
d2c0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74   deleted when it
d2d0: 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68   is closed.  ^Th
d2e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d2f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
d300: 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72   will be set for
d310: 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20   TEMP databases 
d320: 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61  and their journa
d330: 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a  ls, transient.**
d340: 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20   databases, and 
d350: 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a  subjournals..**.
d360: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
d370: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20  OPEN_EXCLUSIVE] 
d380: 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75  flag is always u
d390: 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69  sed in conjuncti
d3a0: 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  on.** with the [
d3b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
d3c0: 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20  TE] flag, which 
d3d0: 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c  are both directl
d3e0: 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74  y.** analogous t
d3f0: 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64  o the O_EXCL and
d400: 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f   O_CREAT flags o
d410: 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e  f the POSIX open
d420: 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20  ().** API.  The 
d430: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
d440: 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e  USIVE flag, when
d450: 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65   paired with the
d460: 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e   .** SQLITE_OPEN
d470: 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64  _CREATE, is used
d480: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
d490: 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c  t file should al
d4a0: 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74  ways.** be creat
d4b0: 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20  ed, and that it 
d4c0: 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69  is an error if i
d4d0: 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73  t already exists
d4e0: 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f  ..** It is <i>no
d4f0: 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e  t</i> used to in
d500: 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20  dicate the file 
d510: 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64  should be opened
d520: 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69   .** for exclusi
d530: 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a  ve access..**.**
d540: 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46   ^At least szOsF
d550: 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  ile bytes of mem
d560: 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65  ory are allocate
d570: 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74  d by SQLite.** t
d580: 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c  o hold the  [sql
d590: 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63  ite3_file] struc
d5a0: 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74  ture passed as t
d5b0: 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75  he third.** argu
d5c0: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20  ment to xOpen.  
d5d0: 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  The xOpen method
d5e0: 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74   does not have t
d5f0: 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68  o.** allocate th
d600: 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20  e structure; it 
d610: 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c  should just fill
d620: 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68   it in.  Note th
d630: 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20  at.** the xOpen 
d640: 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20  method must set 
d650: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
d660: 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74  .pMethods to eit
d670: 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b  her.** a valid [
d680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d690: 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f  ds] object or to
d6a0: 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75   NULL.  xOpen mu
d6b0: 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76  st do.** this ev
d6c0: 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66  en if the open f
d6d0: 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78  ails.  SQLite ex
d6e0: 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73  pects that the s
d6f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
d700: 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20  hods.** element 
d710: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66  will be valid af
d720: 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e  ter xOpen return
d730: 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  s regardless of 
d740: 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f  the success.** o
d750: 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65  r failure of the
d760: 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a   xOpen call..**.
d770: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
d780: 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54  .xAccess]].** ^T
d790: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
d7a0: 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d  t to xAccess() m
d7b0: 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43  ay be [SQLITE_AC
d7c0: 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20  CESS_EXISTS].** 
d7d0: 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20  to test for the 
d7e0: 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66  existence of a f
d7f0: 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ile, or [SQLITE_
d800: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
d810: 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65  ] to.** test whe
d820: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72  ther a file is r
d830: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
d840: 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  able, or [SQLITE
d850: 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a  _ACCESS_READ].**
d860: 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72   to test whether
d870: 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65   a file is at le
d880: 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20  ast readable.   
d890: 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20  The file can be 
d8a0: 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a  a.** directory..
d8b0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  **.** ^SQLite wi
d8c0: 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61  ll always alloca
d8d0: 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61  te at least mxPa
d8e0: 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66  thname+1 bytes f
d8f0: 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74  or the.** output
d900: 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74   buffer xFullPat
d910: 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63  hname.  The exac
d920: 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75  t size of the ou
d930: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d940: 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73  s also passed as
d950: 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   a parameter to 
d960: 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49  both  methods. I
d970: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d980: 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61  fer.** is not la
d990: 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c  rge enough, [SQL
d9a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68  ITE_CANTOPEN] sh
d9b0: 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
d9c0: 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a  . Since this is.
d9d0: 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20  ** handled as a 
d9e0: 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53  fatal error by S
d9f0: 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65  QLite, vfs imple
da00: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
da10: 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f  d endeavor.** to
da20: 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79   prevent this by
da30: 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e   setting mxPathn
da40: 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69  ame to a suffici
da50: 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75  ently large valu
da60: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61  e..**.** The xRa
da70: 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65  ndomness(), xSle
da80: 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69  ep(), xCurrentTi
da90: 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65  me(), and xCurre
daa0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a  ntTimeInt64().**
dab0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
dac0: 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70  not strictly a p
dad0: 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73  art of the files
dae0: 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20  ystem, but they 
daf0: 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20  are.** included 
db00: 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63  in the VFS struc
db10: 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74  ture for complet
db20: 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52  eness..** The xR
db30: 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63  andomness() func
db40: 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f  tion attempts to
db50: 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62   return nBytes b
db60: 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d  ytes.** of good-
db70: 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65  quality randomne
db80: 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54  ss into zOut.  T
db90: 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
dba0: 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c  is.** the actual
dbb0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
dbc0: 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f   of randomness o
dbd0: 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  btained..** The 
dbe0: 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20  xSleep() method 
dbf0: 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69  causes the calli
dc00: 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65  ng thread to sle
dc10: 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61  ep for at.** lea
dc20: 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  st the number of
dc30: 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69   microseconds gi
dc40: 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72  ven.  ^The xCurr
dc50: 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74  entTime().** met
dc60: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75  hod returns a Ju
dc70: 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20  lian Day Number 
dc80: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
dc90: 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73  date and time as
dca0: 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70  .** a floating p
dcb0: 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e  oint value..** ^
dcc0: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
dcd0: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72  Int64() method r
dce0: 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e  eturns, as an in
dcf0: 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61  teger, the Julia
dd00: 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20  n.** Day Number 
dd10: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36  multiplied by 86
dd20: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
dd30: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
dd40: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
dd50: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
dd60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
dd70: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
dd80: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
dd90: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
dda0: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
ddb0: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
ddc0: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
ddd0: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
dde0: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
ddf0: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
de00: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
de10: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
de20: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
de30: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
de40: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
de50: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
de60: 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ble..**.** ^The 
de70: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xSetSystemCall()
de80: 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c  , xGetSystemCall
de90: 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73  (), and xNestSys
dea0: 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66  temCall() interf
deb0: 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  aces.** are not 
dec0: 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69  used by the SQLi
ded0: 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20  te core.  These 
dee0: 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61  optional interfa
def0: 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64  ces are provided
df00: 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65  .** by some VFSe
df10: 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20  s to facilitate 
df20: 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56  testing of the V
df30: 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72  FS code. By over
df40: 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65  riding .** syste
df50: 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e  m calls with fun
df60: 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73  ctions under its
df70: 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74   control, a test
df80: 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20   program can.** 
df90: 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20  simulate faults 
dfa0: 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74  and error condit
dfb0: 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20  ions that would 
dfc0: 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66  otherwise be dif
dfd0: 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70  ficult.** or imp
dfe0: 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63  ossible to induc
dff0: 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73  e.  The set of s
e000: 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74  ystem calls that
e010: 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64   can be overridd
e020: 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f  en.** varies fro
e030: 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f  m one VFS to ano
e040: 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f  ther, and from o
e050: 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ne version of th
e060: 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68  e same VFS to th
e070: 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c  e.** next.  Appl
e080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73  ications that us
e090: 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  e these interfac
e0a0: 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61  es must be prepa
e0b0: 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f  red for any.** o
e0c0: 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69  r all of these i
e0d0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20  nterfaces to be 
e0e0: 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69  NULL or for thei
e0f0: 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68  r behavior to ch
e100: 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65  ange.** from one
e110: 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20   release to the 
e120: 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
e130: 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74  ons must not att
e140: 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a  empt to access.*
e150: 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d  * any of these m
e160: 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56  ethods if the iV
e170: 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46  ersion of the VF
e180: 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33  S is less than 3
e190: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
e1a0: 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
e1b0: 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70  sqlite3_vfs;.typ
e1c0: 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
e1d0: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e1e0: 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73  (void);.struct s
e1f0: 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69  qlite3_vfs {.  i
e200: 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20  nt iVersion;    
e210: 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63          /* Struc
e220: 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d  ture version num
e230: 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33  ber (currently 3
e240: 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46  ) */.  int szOsF
e250: 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20  ile;            
e260: 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c  /* Size of subcl
e270: 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69  assed sqlite3_fi
e280: 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61  le */.  int mxPa
e290: 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20  thname;         
e2a0: 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65   /* Maximum file
e2b0: 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68   pathname length
e2c0: 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66   */.  sqlite3_vf
e2d0: 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f  s *pNext;      /
e2e0: 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65  * Next registere
e2f0: 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74  d VFS */.  const
e300: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20   char *zName;   
e310: 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
e320: 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65  his virtual file
e330: 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69   system */.  voi
e340: 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20  d *pAppData;    
e350: 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72        /* Pointer
e360: 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   to application-
e370: 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f  specific data */
e380: 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28  .  int (*xOpen)(
e390: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e3a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e3b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a   sqlite3_file*,.
e3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
e3d0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e3e0: 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74  OutFlags);.  int
e3f0: 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69   (*xDelete)(sqli
e400: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e410: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e420: 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74   syncDir);.  int
e430: 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69   (*xAccess)(sqli
e440: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e450: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e460: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65   flags, int *pRe
e470: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
e480: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71  FullPathname)(sq
e490: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e4a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e4b0: 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a  nt nOut, char *z
e4c0: 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a  Out);.  void *(*
e4d0: 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  xDlOpen)(sqlite3
e4e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e4f0: 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20  r *zFilename);. 
e500: 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72   void (*xDlError
e510: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e520: 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
e530: 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69  *zErrMsg);.  voi
e540: 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71  d (*(*xDlSym)(sq
e550: 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a  lite3_vfs*,void*
e560: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53  , const char *zS
e570: 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20  ymbol))(void);. 
e580: 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65   void (*xDlClose
e590: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e5a0: 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  void*);.  int (*
e5b0: 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c  xRandomness)(sql
e5c0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
e5d0: 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74  Byte, char *zOut
e5e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65  );.  int (*xSlee
e5f0: 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  p)(sqlite3_vfs*,
e600: 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64   int microsecond
e610: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72  s);.  int (*xCur
e620: 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65  rentTime)(sqlite
e630: 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29  3_vfs*, double*)
e640: 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61  ;.  int (*xGetLa
e650: 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  stError)(sqlite3
e660: 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72  _vfs*, int, char
e670: 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54   *);.  /*.  ** T
e680: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e690: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20   are in version 
e6a0: 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  1 of the sqlite_
e6b0: 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20  vfs object.  ** 
e6c0: 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f  definition.  Tho
e6d0: 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61  se that follow a
e6e0: 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73  re added in vers
e6f0: 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20  ion 2 or later. 
e700: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72   */.  int (*xCur
e710: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73  rentTimeInt64)(s
e720: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c  qlite3_vfs*, sql
e730: 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20  ite3_int64*);.  
e740: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e750: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e760: 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20   versions 1 and 
e770: 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  2 of the sqlite_
e780: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e790: 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65   Those below are
e7a0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61   for version 3 a
e7b0: 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f  nd greater..  */
e7c0: 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73  .  int (*xSetSys
e7d0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e7e0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e7f0: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e800: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a  3_syscall_ptr);.
e810: 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c    sqlite3_syscal
e820: 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74  l_ptr (*xGetSyst
e830: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e840: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e850: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73   *zName);.  cons
e860: 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53  t char *(*xNextS
e870: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e880: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e890: 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f  har *zName);.  /
e8a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
e8b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
e8c0: 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75  versions 1 throu
e8d0: 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69  gh 3 of the sqli
e8e0: 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20  te_vfs object.. 
e8f0: 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d   ** New fields m
e900: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69  ay be appended i
e910: 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e  n figure version
e920: 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e  s.  The iVersion
e930: 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c  .  ** value will
e940: 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65   increment whene
e950: 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73  ver this happens
e960: 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  . .  */.};../*.*
e970: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
e980: 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73  s for the xAcces
e990: 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a  s VFS method.**.
e9a0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
e9b0: 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62   constants can b
e9c0: 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68  e used as the th
e9d0: 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
e9e0: 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20  .** the xAccess 
e9f0: 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71  method of an [sq
ea00: 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
ea10: 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69  t.  They determi
ea20: 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20  ne.** what kind 
ea30: 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74  of permissions t
ea40: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
ea50: 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72  d is looking for
ea60: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ea70: 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20  _ACCESS_EXISTS, 
ea80: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ea90: 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65  od.** simply che
eaa0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eab0: 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20  file exists..** 
eac0: 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
ead0: 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68  SS_READWRITE, th
eae0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
eaf0: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
eb00: 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72  er the named dir
eb10: 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72  ectory is both r
eb20: 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74  eadable and writ
eb30: 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65  able.** (in othe
eb40: 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65  r words, if file
eb50: 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20  s can be added, 
eb60: 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e  removed, and ren
eb70: 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74  amed within.** t
eb80: 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a  he directory)..*
eb90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43  * The SQLITE_ACC
eba0: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f  ESS_READWRITE co
ebb0: 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e  nstant is curren
ebc0: 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79  tly used only by
ebd0: 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74   the.** [temp_st
ebe0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72  ore_directory pr
ebf0: 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68  agma], though th
ec00: 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20  is could change 
ec10: 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72  in a future.** r
ec20: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
ec30: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
ec40: 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68  _ACCESS_READ, th
ec50: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
ec60: 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68  .** checks wheth
ec70: 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72  er the file is r
ec80: 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51  eadable.  The SQ
ec90: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
eca0: 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20   constant is.** 
ecb0: 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64  currently unused
ecc0: 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68  , though it migh
ecd0: 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66  t be used in a f
ece0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
ecf0: 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23  .** SQLite..*/.#
ed00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed10: 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30  CESS_EXISTS    0
ed20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ed30: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
ed40: 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20   1   /* Used by 
ed50: 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72  PRAGMA temp_stor
ed60: 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23  e_directory */.#
ed70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
ed80: 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32  CESS_READ      2
ed90: 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a     /* Unused */.
eda0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
edb0: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
edc0: 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68  ShmLock VFS meth
edd0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
ede0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
edf0: 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69   define the vari
ee00: 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72  ous locking oper
ee10: 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65  ations.** allowe
ee20: 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63  d by the xShmLoc
ee30: 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c  k method of [sql
ee40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
ee50: 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  .  The.** follow
ee60: 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79  ing are the only
ee70: 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69   legal combinati
ee80: 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20  ons of flags to 
ee90: 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20  the.** xShmLock 
eea0: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
eeb0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  l>.** <li>  SQLI
eec0: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51  TE_SHM_LOCK | SQ
eed0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
eee0: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eef0: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
ef00: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
ef10: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ef20: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ef30: 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
ef40: 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
ef50: 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
ef60: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ef70: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ef80: 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20  When unlocking, 
ef90: 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20  the same SHARED 
efa0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61  or EXCLUSIVE fla
efb0: 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69  g must be suppli
efc0: 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76  ed as.** was giv
efd0: 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73  en on the corres
efe0: 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a  ponding lock.  .
eff0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
f000: 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72  ck method can tr
f010: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
f020: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48   unlocked and SH
f030: 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65  ARED or.** betwe
f040: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f050: 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63  EXCLUSIVE.  It c
f060: 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e  annot transition
f070: 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a   between SHARED.
f080: 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ** and EXCLUSIVE
f090: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
f0a0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20  ITE_SHM_UNLOCK  
f0b0: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
f0c0: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20  QLITE_SHM_LOCK  
f0d0: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
f0e0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f0f0: 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69  ED       4.#defi
f100: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58  ne SQLITE_SHM_EX
f110: 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a  CLUSIVE    8../*
f120: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61  .** CAPI3REF: Ma
f130: 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69  ximum xShmLock i
f140: 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ndex.**.** The x
f150: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
f160: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
f170: 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76  thods] may use v
f180: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
f190: 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65   0 and this uppe
f1a0: 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22  r bound as its "
f1b0: 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74  offset" argument
f1c0: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  ..** The SQLite 
f1d0: 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  core will never 
f1e0: 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69  attempt to acqui
f1f0: 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a  re or release a.
f200: 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20  ** lock outside 
f210: 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f  of this range.*/
f220: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f230: 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20  SHM_NLOCK       
f240: 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   8.../*.** CAPI3
f250: 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20  REF: Initialize 
f260: 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
f270: 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
f280: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f290: 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69  () routine initi
f2a0: 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51  alizes the.** SQ
f2b0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e  Lite library.  ^
f2c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74  The sqlite3_shut
f2d0: 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a  down() routine.*
f2e0: 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e  * deallocates an
f2f0: 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74  y resources that
f300: 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20   were allocated 
f310: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
f320: 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73  alize()..** Thes
f330: 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  e routines are d
f340: 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69  esigned to aid i
f350: 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61  n process initia
f360: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  lization and.** 
f370: 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65  shutdown on embe
f380: 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57  dded systems.  W
f390: 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69  orkstation appli
f3a0: 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a  cations using.**
f3b0: 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79   SQLite normally
f3c0: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20   do not need to 
f3d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66  invoke either of
f3e0: 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
f3f0: 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f  .**.** A call to
f400: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f410: 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66  ize() is an "eff
f420: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
f430: 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72  it is.** the fir
f440: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f450: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f460: 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74  invoked during t
f470: 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a  he lifetime of.*
f480: 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f  * the process, o
f490: 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66  r if it is the f
f4a0: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f4b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f4c0: 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c  s invoked.** fol
f4d0: 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f  lowing a call to
f4e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f4f0: 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20  n().  ^(Only an 
f500: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a  effective call.*
f510: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69  * of sqlite3_ini
f520: 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61  tialize() does a
f530: 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ny initializatio
f540: 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61  n.  All other ca
f550: 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c  lls.** are harml
f560: 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a  ess no-ops.)^.**
f570: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
f580: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f590: 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
f5a0: 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
f5b0: 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61   the first.** ca
f5c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
f5d0: 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74  utdown() since t
f5e0: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
f5f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e  initialize().  ^
f600: 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65  (Only.** an effe
f610: 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71  ctive call to sq
f620: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f630: 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74   does any deinit
f640: 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41  ialization..** A
f650: 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63  ll other valid c
f660: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
f670: 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68  shutdown() are h
f680: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
f690: 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ^.**.** The sqli
f6a0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f6b0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68   interface is th
f6c0: 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71  readsafe, but sq
f6d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f6e0: 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65  .** is not.  The
f6f0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f700: 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75  n() interface mu
f710: 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  st only be calle
f720: 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67  d from a.** sing
f730: 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20  le thread.  All 
f740: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
f750: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74  onnections] must
f760: 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61   be closed and a
f770: 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69  ll.** other SQLi
f780: 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73  te resources mus
f790: 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  t be deallocated
f7a0: 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69   prior to invoki
f7b0: 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68  ng.** sqlite3_sh
f7c0: 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20  utdown()..**.** 
f7d0: 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  Among other thin
f7e0: 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69  gs, ^sqlite3_ini
f7f0: 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69  tialize() will i
f800: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
f810: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d  _os_init().  Sim
f820: 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33  ilarly, ^sqlite3
f830: 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77  _shutdown().** w
f840: 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ill invoke sqlit
f850: 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a  e3_os_end()..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f880: 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51  tine returns [SQ
f890: 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
f8a0: 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20  ess..** ^If for 
f8b0: 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c  some reason, sql
f8c0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f8d0: 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69  ) is unable to i
f8e0: 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65  nitialize.** the
f8f0: 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70   library (perhap
f900: 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74  s it is unable t
f910: 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65  o allocate a nee
f920: 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63  ded resource suc
f930: 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29  h.** as a mutex)
f940: 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b   it returns an [
f950: 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65  error code] othe
f960: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
f970: 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  K]..**.** ^The s
f980: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f990: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  e() routine is c
f9a0: 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  alled internally
f9b0: 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a   by many other.*
f9c0: 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
f9d0: 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61  ces so that an a
f9e0: 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c  pplication usual
f9f0: 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ly does not need
fa00: 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71   to.** invoke sq
fa10: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fa20: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f  () directly.  Fo
fa30: 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69  r example, [sqli
fa40: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63  te3_open()].** c
fa50: 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69  alls sqlite3_ini
fa60: 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65  tialize() so the
fa70: 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
fa80: 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
fa90: 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c  cally.** initial
faa0: 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  ized when [sqlit
fab0: 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61  e3_open()] is ca
fac0: 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e  lled if it has n
fad0: 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65  ot be initialize
fae0: 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e  d.** already.  ^
faf0: 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69  However, if SQLi
fb00: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fb10: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
fb20: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a  OMIT_AUTOINIT].*
fb30: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
fb40: 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ption, then the 
fb50: 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20  automatic calls 
fb60: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
fb70: 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f  alize().** are o
fb80: 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61  mitted and the a
fb90: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
fba0: 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69  call sqlite3_ini
fbb0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
fbc0: 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75  ly.** prior to u
fbd0: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
fbe0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
fbf0: 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f    For maximum po
fc00: 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74  rtability,.** it
fc10: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fc20: 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
fc30: 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20  s always invoke 
fc40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fc50: 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79  ze().** directly
fc60: 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
fc70: 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
fc80: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74   interface.  Fut
fc90: 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20  ure releases.** 
fca0: 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65  of SQLite may re
fcb0: 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20  quire this.  In 
fcc0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
fcd0: 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69   behavior exhibi
fce0: 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69  ted.** when SQLi
fcf0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
fd00: 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  ith [SQLITE_OMIT
fd10: 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74  _AUTOINIT] might
fd20: 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64   become the.** d
fd30: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
fd40: 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
fd50: 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
fd60: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
fd70: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f  te3_os_init() ro
fd80: 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61  utine does opera
fd90: 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
fda0: 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ific.** initiali
fdb0: 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51  zation of the SQ
fdc0: 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54  Lite library.  T
fdd0: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  he sqlite3_os_en
fde0: 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75  d().** routine u
fdf0: 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74  ndoes the effect
fe00: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
fe10: 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20  nit().  Typical 
fe20: 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d  tasks.** perform
fe30: 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74  ed by these rout
fe40: 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c  ines include all
fe50: 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c  ocation or deall
fe60: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74  ocation.** of st
fe70: 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20  atic resources, 
fe80: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
fe90: 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c  f global variabl
fea0: 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75  es,.** setting u
feb0: 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  p a default [sql
fec0: 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65  ite3_vfs] module
fed0: 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a  , or setting up.
fee0: 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e  ** a default con
fef0: 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67  figuration using
ff00: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
ff10: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ()]..**.** The a
ff20: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ff30: 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65  d never invoke e
ff40: 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73  ither sqlite3_os
ff50: 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71  _init().** or sq
ff60: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64  lite3_os_end() d
ff70: 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70  irectly.  The ap
ff80: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
ff90: 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20   only invoke.** 
ffa0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ffb0: 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  ze() and sqlite3
ffc0: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68  _shutdown().  Th
ffd0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
ffe0: 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  t().** interface
fff0: 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d   is called autom
10000 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
10010 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
10020 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
10030 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c  os_end() is call
10040 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68  ed by sqlite3_sh
10050 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f  utdown().  Appro
10060 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d  priate.** implem
10070 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71  entations for sq
10080 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
10090 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
100a0 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c  nd().** are buil
100b0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68  t into SQLite wh
100c0 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65  en it is compile
100d0 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64  d for Unix, Wind
100e0 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a  ows, or OS/2..**
100f0 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75   When [custom bu
10100 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72  ilds | built for
10110 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73   other platforms
10120 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20  ].** (using the 
10130 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52  [SQLITE_OS_OTHER
10140 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =1] compile-time
10150 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20  .** option) the 
10160 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
10170 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62   supply a suitab
10180 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
10190 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  n for.** sqlite3
101a0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
101b0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
101c0 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e    An application
101d0 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70  -supplied.** imp
101e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
101f0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10200 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
10210 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74  nd().** must ret
10220 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
10230 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73  on success and s
10240 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72  ome other [error
10250 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66   code] upon.** f
10260 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54  ailure..*/.SQLIT
10270 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
10280 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
10290 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
102a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
102b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
102c0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
102d0 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  n(void);.SQLITE_
102e0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
102f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f  TDCALL sqlite3_o
10300 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
10310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
10320 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
10330 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
10340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10350 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
10360 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
10370 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
10380 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
10390 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
103a0 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
103b0 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
103c0 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
103d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
103e0 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
103f0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
10400 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
10410 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
10420 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
10430 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
10440 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
10450 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
10460 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
10470 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
10480 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
10490 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
104a0 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
104b0 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
104c0 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
104d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
104e0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
104f0 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
10500 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
10510 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
10520 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10530 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
10540 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
10550 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
10560 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
10570 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
10580 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
10590 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
105a0 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
105b0 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
105c0 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
105d0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
105e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
105f0 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
10600 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
10610 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
10620 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
10630 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
10640 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
10650 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10660 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
10670 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
10680 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
10690 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
106a0 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
106b0 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
106c0 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
106d0 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
106e0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
106f0 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
10700 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
10710 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
10720 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
10730 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
10740 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
10750 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
10760 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
10770 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10780 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
10790 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
107a0 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
107b0 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
107c0 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
107d0 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
107e0 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
107f0 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10800 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10810 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10820 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10830 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10840 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10850 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10860 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
10870 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
10880 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
10890 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
108a0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
108b0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
108c0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
108d0 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
108e0 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
108f0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
10900 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  int SQLITE_CDECL
10910 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10920 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10930 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10940 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10950 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
10960 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
10970 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10980 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
10990 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
109a0 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
109b0 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
109c0 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
109d0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
109e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
109f0 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
10a00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
10a10 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
10a20 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
10a30 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
10a40 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10a50 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
10a60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10a70 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
10a80 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
10a90 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
10aa0 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
10ab0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
10ac0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
10ad0 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
10ae0 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
10af0 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
10b00 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
10b10 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
10b20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10b30 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
10b40 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
10b50 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
10b60 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
10b70 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
10b80 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
10b90 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
10ba0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10bb0 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
10bc0 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
10bd0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
10be0 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
10bf0 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ssful..*/.SQLITE
10c00 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
10c10 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64 62  CDECL sqlite3_db
10c20 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
10c30 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
10c40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10c50 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
10c60 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
10c70 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
10c80 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
10c90 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
10ca0 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
10cb0 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
10cc0 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
10cd0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
10ce0 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
10cf0 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
10d00 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
10d10 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
10d20 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
10d30 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
10d40 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
10d50 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
10d60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10d70 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
10d80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10d90 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
10da0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
10db0 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
10dc0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
10dd0 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
10de0 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
10df0 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
10e00 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
10e10 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
10e20 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
10e30 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
10e40 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
10e50 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
10e60 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
10e70 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
10e80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10e90 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
10ea0 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
10eb0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
10ec0 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
10ed0 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
10ee0 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
10ef0 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
10f00 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
10f10 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
10f20 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
10f30 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
10f40 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
10f50 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
10f60 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
10f70 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
10f80 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
10f90 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
10fa0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
10fb0 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
10fc0 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
10fd0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
10fe0 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
10ff0 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
11000 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
11010 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
11020 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
11030 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
11040 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
11050 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
11060 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
11070 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
11080 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
11090 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
110a0 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
110b0 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
110c0 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
110d0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
110e0 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c  alloc, xRealloc,
110f0 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f   and xFree metho
11100 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b  ds must work lik
11110 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28  e the.** malloc(
11120 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  ), realloc() and
11130 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
11140 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
11150 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
11160 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
11170 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
11180 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11190 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
111a0 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
111b0 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
111c0 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
111d0 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65  dup..**.** xSize
111e0 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74   should return t
111f0 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
11200 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  e of a memory al
11210 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76  location.** prev
11220 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20  iously obtained 
11230 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20  from xMalloc or 
11240 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61  xRealloc.  The a
11250 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a  llocated size.**
11260 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65   is always at le
11270 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68  ast as big as th
11280 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  e requested size
11290 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
112a0 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  er..**.** The xR
112b0 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65  oundup method re
112c0 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64  turns what would
112d0 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65   be the allocate
112e0 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d  d size of.** a m
112f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11300 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75   given a particu
11310 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69  lar requested si
11320 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79  ze.  Most memory
11330 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  .** allocators r
11340 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61  ound up memory a
11350 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65  llocations at le
11360 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20  ast to the next 
11370 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38  multiple.** of 8
11380 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f  .  Some allocato
11390 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61  rs round up to a
113a0 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65   larger multiple
113b0 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f   or to a power o
113c0 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65  f 2..** Every me
113d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
113e0 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69  request coming i
113f0 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74  n through [sqlit
11400 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  e3_malloc()].** 
11410 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
11420 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c  loc()] first cal
11430 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66  ls xRoundup.  If
11440 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e   xRoundup return
11450 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61  s 0, .** that ca
11460 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70  uses the corresp
11470 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c  onding memory al
11480 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c  location to fail
11490 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69  ..**.** The xIni
114a0 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c  t method initial
114b0 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  izes the memory 
114c0 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20  allocator.  For 
114d0 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
114e0 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
114f0 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
11500 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
11510 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
11520 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
11530 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
11540 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
11550 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
11560 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11570 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
11580 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
11590 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
115a0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
115b0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
115c0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
115d0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
115e0 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
115f0 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
11600 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
11610 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
11620 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
11630 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
11640 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
11650 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
11660 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
11670 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
11680 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
11690 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
116a0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
116b0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
116c0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
116d0 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
116e0 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
116f0 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
11700 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
11710 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
11720 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
11730 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
11740 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
11750 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
11760 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11770 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
11780 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
11790 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
117a0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
117b0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
117c0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
117d0 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
117e0 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
117f0 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
11800 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
11810 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
11820 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
11830 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
11840 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
11850 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
11860 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
11870 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
11880 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
11890 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
118a0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
118b0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
118c0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
118d0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
118e0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
118f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
11900 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
11910 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
11920 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
11930 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
11940 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
11950 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
11960 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
11970 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
11980 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
11990 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
119a0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
119b0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
119c0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
119d0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
119e0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
119f0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
11a00 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
11a10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
11a20 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
11a30 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
11a40 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
11a50 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
11a60 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
11a70 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
11a80 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
11a90 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
11aa0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11ab0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
11ac0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
11ad0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
11ae0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
11af0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
11b00 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
11b10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
11b20 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
11b30 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
11b40 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
11b50 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
11b60 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
11b70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11b80 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
11b90 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
11ba0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
11bb0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
11bc0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
11bd0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
11be0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
11bf0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11c00 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
11c10 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
11c20 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
11c30 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
11c40 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11c50 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
11c60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11c70 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
11c80 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
11c90 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
11ca0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
11cb0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11cc0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
11cd0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
11ce0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
11cf0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
11d00 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
11d10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
11d20 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
11d30 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
11d40 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
11d50 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11d60 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
11d70 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
11d80 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
11d90 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
11da0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
11db0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11dc0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
11dd0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
11de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11df0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
11e00 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11e10 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
11e20 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
11e30 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
11e40 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
11e50 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
11e60 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
11e70 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
11e80 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
11e90 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
11ea0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
11eb0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
11ec0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
11ed0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
11ee0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
11ef0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
11f00 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
11f10 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11f20 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
11f30 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
11f40 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11f50 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
11f60 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
11f70 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
11f80 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
11f90 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
11fa0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
11fb0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
11fc0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
11fd0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
11fe0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
11ff0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
12000 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
12010 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
12020 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12030 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
12040 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
12050 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12060 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12070 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12080 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
12090 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
120a0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
120b0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
120c0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
120d0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
120e0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
120f0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
12100 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12110 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12120 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
12130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12140 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
12150 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
12160 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
12170 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
12180 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
12190 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
121a0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
121b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
121c0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
121d0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
121e0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
121f0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
12200 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
12210 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
12220 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
12230 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
12240 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
12250 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
12260 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
12270 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
12280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
12290 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
122a0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
122b0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
122c0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
122d0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
122e0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
122f0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12300 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
12310 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
12320 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
12330 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
12340 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
12350 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
12360 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
12370 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
12380 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
12390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
123a0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
123b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
123c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
123d0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
123e0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
123f0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12400 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
12410 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
12420 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
12430 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
12440 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
12450 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12460 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
12470 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
12480 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
12490 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
124a0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
124b0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
124c0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
124d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124e0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124f0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
12500 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
12510 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
12520 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
12530 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12540 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
12550 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
12560 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
12570 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
12580 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
12590 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
125a0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
125b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
125c0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
125d0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
125e0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
125f0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
12600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
12610 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
12620 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12630 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
12640 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
12650 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
12660 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12670 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12680 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12690 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
126a0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
126b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
126c0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
126d0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
126e0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
126f0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
12700 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
12710 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
12720 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
12730 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
12740 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
12750 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
12760 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
12770 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
12780 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12790 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
127a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
127b0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
127c0 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
127d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f  _CONFIG_MALLOC o
127e0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
127f0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12800 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
12810 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
12820 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
12830 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12840 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54   structure..** T
12850 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
12860 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
12870 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
12880 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12890 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
128a0 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
128b0 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
128c0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
128d0 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
128e0 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
128f0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
12900 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
12910 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
12920 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
12930 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
12940 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
12950 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
12960 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
12970 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
12980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
12990 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
129a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
129b0 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
129c0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
129d0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
129e0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
129f0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12a00 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
12a10 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12a20 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12a30 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12a40 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
12a50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
12a60 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12a70 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12a80 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12a90 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
12aa0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
12ab0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
12ac0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
12ad0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
12ae0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
12af0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
12b00 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
12b10 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
12b20 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
12b30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
12b40 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
12b50 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
12b60 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
12b70 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12b80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12b90 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
12ba0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12bb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
12bc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12bd0 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f  _MEMSTATUS optio
12be0 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
12bf0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
12c00 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65  int,.** interpre
12c10 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
12c20 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12c30 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
12c40 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a  collection of.**
12c50 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c60 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  on statistics. ^
12c70 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
12c80 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
12c90 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  cs are.** disabl
12ca0 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ed, the followin
12cb0 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
12cc0 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
12cd0 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
12ce0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
12cf0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12d00 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
12d10 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12d20 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
12d30 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
12d40 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
12d50 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
12d60 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
12d70 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  64()].**   </ul>
12d80 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
12d90 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12da0 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12db0 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12dc0 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12dd0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12de0 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12df0 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12e00 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12e10 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12e20 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12e30 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
12e40 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
12e50 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12e60 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
12e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12e80 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
12e90 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
12ea0 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69  FIG_SCRATCH opti
12eb0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
12ec0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
12ed0 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  fer.** that SQLi
12ee0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73  te can use for s
12ef0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20  cratch memory.  
12f00 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72 65  ^(There are thre
12f10 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74  e arguments.** t
12f20 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
12f30 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e  SCRATCH:  A poin
12f40 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a  ter an 8-byte.**
12f50 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20   aligned memory 
12f60 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63  buffer from whic
12f70 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c  h the scratch al
12f80 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62  locations will b
12f90 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20  e.** drawn, the 
12fa0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72  size of each scr
12fb0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  atch allocation 
12fc0 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65  (sz),.** and the
12fd0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
12fe0 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  of scratch alloc
12ff0 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a  ations (N).)^.**
13000 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13010 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
13020 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
13030 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
13040 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
13050 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
13060 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
13070 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d  e will not use m
13080 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72  ore than one scr
13090 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
130a0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c   thread..** ^SQL
130b0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
130c0 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63 68  equest a scratch
130d0 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
130e0 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
130f0 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
13100 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20  e page size..** 
13110 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  ^If SQLite needs
13120 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61   needs additiona
13130 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d  l.** scratch mem
13140 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ory beyond what 
13150 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
13160 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
13170 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a  n option, then .
13180 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
13190 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73  oc()] will be us
131a0 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65  ed to obtain the
131b0 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c   memory needed.<
131c0 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  p>.** ^When the 
131d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76  application prov
131e0 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20  ides any amount 
131f0 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  of scratch memor
13200 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54  y using.** SQLIT
13210 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
13220 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  , SQLite avoids 
13230 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67  unnecessary larg
13240 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
13250 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61  lloc|heap alloca
13260 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20  tions]..** This 
13270 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e  can help [Robson
13280 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d   proof|prevent m
13290 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
132a0 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74   failures] due t
132b0 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65  o heap.** fragme
132c0 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d  ntation in low-m
132d0 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73  emory embedded s
132e0 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  ystems..** </dd>
132f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13300 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13310 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13320 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
13330 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
13350 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20  AGECACHE option 
13360 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
13370 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
13380 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13390 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20  can use for the 
133a0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61  database page ca
133b0 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66  che with the def
133c0 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63  ault page.** cac
133d0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
133e0 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
133f0 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
13400 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
13410 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13420 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13430 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
13440 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
13450 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
13460 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 0a  CONFIG_PCACHE2].
13470 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
13480 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68 65   option..** ^The
13490 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
134a0 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45  uments to SQLITE
134b0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
134c0 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 0a  E: A pointer to.
134d0 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  ** 8-byte aligne
134e0 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
134f0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
13500 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
13510 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
13520 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
13530 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
13540 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
13550 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
13560 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
13570 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
13580 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
13590 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20 73  nd 65536) plus s
135a0 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73 20  ome extra bytes 
135b0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65  for each.** page
135c0 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 6e   header.  ^The n
135d0 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20 62  umber of extra b
135e0 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20 74  ytes needed by t
135f0 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a 2a  he page header.*
13600 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  * can be determi
13610 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53  ned using the [S
13620 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13630 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69 6f  CHE_HDRSZ] optio
13640 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  n .** to [sqlite
13650 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 20  3_config()]..** 
13660 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13670 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13680 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13690 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
136a0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
136b0 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
136c0 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ry.  The first.*
136d0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
136e0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  d pointer to an 
136f0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62  8-byte aligned b
13700 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 74  lock of memory t
13710 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65 61  hat.** is at lea
13720 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
13730 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77 69   memory, otherwi
13740 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  se subsequent be
13750 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
13760 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c 69  efined..** ^SQLi
13770 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
13780 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
13790 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
137a0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
137b0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
137c0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
137d0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
137e0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
137f0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
13800 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
13810 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
13820 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
13830 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
13840 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
13850 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
13860 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
13870 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
13880 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
13890 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ace.</dd>.**.** 
138a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
138b0 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
138c0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
138d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
138e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
138f0 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  AP option specif
13900 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
13910 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20 74  ory buffer .** t
13920 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13930 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13940 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
13950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13960 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f  ds.** beyond tho
13970 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  se provided for 
13980 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
13990 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a  G_SCRATCH] and.*
139a0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
139b0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
139c0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
139d0 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 69  IG_HEAP option i
139e0 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
139f0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
13a00 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65  mpiled.** with e
13a10 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
13a20 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
13a30 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
13a40 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65 74  MEMSYS5] and ret
13a50 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
13a60 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65  ERROR] if invoke
13a70 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20  d otherwise..** 
13a80 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13a90 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13aa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13ab0 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20 61  :.** An 8-byte a
13ac0 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
13ad0 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
13ae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
13af0 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
13b00 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
13b10 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
13b20 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
13b30 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
13b40 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
13b50 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
13b60 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
13b70 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
13b80 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
13b90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13ba0 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
13bb0 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
13bc0 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
13bd0 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
13be0 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
13bf0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
13c00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
13c10 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
13c20 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  ot NULL then the
13c30 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
13c40 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
13c50 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
13c60 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
13c70 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
13c80 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
13c90 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
13ca0 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
13cb0 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
13cc0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
13cd0 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
13ce0 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
13cf0 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
13d00 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
13d10 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
13d20 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13d30 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
13d40 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
13d50 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
13d60 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
13d70 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
13d80 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
13d90 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
13da0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13db0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13dc0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
13dd0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13de0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13df0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
13e00 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
13e10 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 0a  ment which is a.
13e20 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ** pointer to an
13e30 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
13e40 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13e50 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13e60 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
13e70 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61 6c  ent specifies al
13e80 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
13e90 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  vel mutex routin
13ea0 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a  es to be used.**
13eb0 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d 75   in place the mu
13ec0 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69  tex routines bui
13ed0 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
13ee0 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
13ef0 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
13f00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
13f10 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
13f20 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
13f30 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61  re before the ca
13f40 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
13f50 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75  3_config()] retu
13f60 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  rns. ^If SQLite 
13f70 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13f80 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13f90 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13fa0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13fb0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13fc0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13fd0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13fe0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13ff0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14000 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14010 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14020 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14030 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14040 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66  ONFIG_MUTEX conf
14050 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14060 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
14070 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
14080 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14090 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
140a0 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
140b0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
140c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
140d0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
140e0 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69 6f  G_GETMUTEX optio
140f0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14100 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
14110 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
14120 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14130 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14140 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14150 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
14160 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
14170 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
14180 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
14190 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
141a0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
141b0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
141c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
141d0 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
141e0 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
141f0 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
14200 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
14210 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
14220 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
14230 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
14240 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
14250 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
14260 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
14270 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14280 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14290 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
142a0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
142b0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
142c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
142d0 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
142e0 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
142f0 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
14300 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
14310 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
14320 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
14330 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
14340 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
14350 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
14360 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
14370 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
14380 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
14390 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
143a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
143b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
143c0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
143d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
143e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
143f0 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e  LOOKASIDE option
14400 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
14410 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
14420 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61 75  ine.** the defau
14430 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61  lt size of looka
14440 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65  side memory on e
14450 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ach [database co
14460 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  nnection]..** Th
14470 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14480 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
14490 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
144a0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e  e buffer slot an
144b0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20  d the second is 
144c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
144d0 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64   slots allocated
144e0 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
144f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20  e connection.)^ 
14500 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   ^(SQLITE_CONFIG
14510 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65  _LOOKASIDE.** se
14520 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75 6c  ts the <i>defaul
14530 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
14540 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
14550 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
14560 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20  SIDE].** option 
14570 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
14580 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
14590 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
145a0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
145b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
145c0 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
145d0 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
145e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
145f0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
14600 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14610 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
14620 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
14630 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14640 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  HE2 option takes
14650 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14660 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
14670 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14680 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
14690 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
146a0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
146b0 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
146c0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20 63  interface to a c
146d0 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
146e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
146f0 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61  )^.** ^SQLite ma
14700 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
14710 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  e [sqlite3_pcach
14720 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
14730 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ct.</dd>.**.** [
14740 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14750 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  ETPCACHE2]] <dt>
14760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14770 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  TPCACHE2</dt>.**
14780 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49   <dd> ^(The SQLI
14790 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
147a0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
147b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
147c0 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ent which.** is 
147d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
147e0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
147f0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
14800 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
14810 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72 65   of.** the curre
14820 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  nt page cache im
14830 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
14840 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
14850 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
14860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14870 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14880 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
14890 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45   <dd> The SQLITE
148a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
148b0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  on is used to co
148c0 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69  nfigure the SQLi
148d0 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72  te.** global [er
148e0 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54  ror log]..** (^T
148f0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14900 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _LOG option take
14910 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a  s two arguments:
14920 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a   a pointer to a.
14930 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  ** function with
14940 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72   a call signatur
14950 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69  e of void(*)(voi
14960 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
14970 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70  r*), .** and a p
14980 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20  ointer to void. 
14990 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
149a0 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
149b0 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69  NULL, it is.** i
149c0 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74  nvoked by [sqlit
149d0 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f  e3_log()] to pro
149e0 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e  cess each loggin
149f0 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
14a00 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f  e.** function po
14a10 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74  inter is NULL, t
14a20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  he [sqlite3_log(
14a30 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63  )] interface bec
14a40 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a  omes a no-op..**
14a50 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74   ^The void point
14a60 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73  er that is the s
14a70 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
14a80 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
14a90 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64  LOG is.** passed
14aa0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
14ab0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
14ac0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
14ad0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14ae0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68  r.** function wh
14af0 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63  enever that func
14b00 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e  tion is invoked.
14b10 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61    ^The second pa
14b20 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68  rameter to.** th
14b30 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
14b40 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  n is a copy of t
14b50 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
14b60 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73  er to the corres
14b70 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  ponding.** [sqli
14b80 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20  te3_log()] call 
14b90 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20  and is intended 
14ba0 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20  to be a [result 
14bb0 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b  code] or an.** [
14bc0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
14bd0 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69  code].  ^The thi
14be0 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73  rd parameter pas
14bf0 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65  sed to the logge
14c00 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73  r is.** log mess
14c10 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74  age after format
14c20 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65  ting via [sqlite
14c30 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a  3_snprintf()]..*
14c40 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67  * The SQLite log
14c50 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69  ging interface i
14c60 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b  s not reentrant;
14c70 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63   the logger func
14c80 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64  tion.** supplied
14c90 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
14ca0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76  ion must not inv
14cb0 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69  oke any SQLite i
14cc0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20  nterface..** In 
14cd0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
14ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68   application, th
14cf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
14d00 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
14d10 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  function must be
14d20 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64   threadsafe. </d
14d30 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14d40 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c  E_CONFIG_URI]] <
14d50 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14d60 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68  _URI.** <dd>^(Th
14d70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14d80 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  URI option takes
14d90 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
14da0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a  nt of type int..
14db0 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  ** If non-zero, 
14dc0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
14dd0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
14de0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
14df0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
14e00 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61 6e  .** then URI han
14e10 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
14e20 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49  y disabled.)^ ^I
14e30 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
14e40 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e  s globally.** en
14e50 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
14e60 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20 5b  ames passed to [
14e70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
14e80 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
14e90 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
14ea0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
14eb0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
14ec0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
14ed0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
14ee0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
14ef0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
14f00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
14f10 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
14f20 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
14f30 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
14f40 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
14f50 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14f60 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c  If it is globall
14f70 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65  y disabled, file
14f80 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c  names are.** onl
14f90 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  y interpreted as
14fa0 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c   URIs if the SQL
14fb0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61  ITE_OPEN_URI fla
14fc0 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
14fd0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
14fe0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
14ff0 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74  ed. ^(By default
15000 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
15010 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
15020 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
15030 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
15040 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
15050 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
15060 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
15070 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
15080 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d.)^.**.** [[SQL
15090 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
150a0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
150b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
150c0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
150d0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54  X_SCAN.** <dd>^T
150e0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
150f0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
15100 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SCAN option take
15110 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67  s a single integ
15120 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77  er.** argument w
15130 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72 65  hich is interpre
15140 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e  ted as a boolean
15150 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61   in order to ena
15160 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a  ble or disable.*
15170 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  * the use of cov
15180 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
15190 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
151a0 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  ns in the query 
151b0 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54  optimizer..** ^T
151c0 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
151d0 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64  ng is determined
151e0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49  .** by the [SQLI
151f0 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e  TE_ALLOW_COVERIN
15200 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f  G_INDEX_SCAN] co
15210 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15220 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a  n, or is "on".**
15230 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65   if that compile
15240 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
15250 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20  omitted..** The 
15260 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62  ability to disab
15270 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
15280 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
15290 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
152a0 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73  ans.** is becaus
152b0 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74  e some incorrect
152c0 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20  ly coded legacy 
152d0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67  applications mig
152e0 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a  ht malfunction.*
152f0 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  * when the optim
15300 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
15310 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
15320 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
15330 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
15340 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
15350 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
15360 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
15370 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
15380 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
15390 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
153a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
153b0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
153c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
153d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
153e0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
153f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15400 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
15410 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
15420 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
15430 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
15440 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
15450 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
15460 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
15470 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
15480 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
15490 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
154a0 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
154b0 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
154c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
154d0 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
154e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
154f0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
15500 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
15510 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
15520 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
15530 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15540 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47  TE_ENABLE_SQLLOG
15550 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20  ] pre-processor 
15560 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54  macro defined. T
15570 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15580 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  t should.** be a
15590 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75   pointer to a fu
155a0 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76  nction of type v
155b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
155c0 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72  ite3*,const char
155d0 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20  *, int)..** The 
155e0 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65  second should be
155f0 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29   of type (void*)
15600 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  . The callback i
15610 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65  s invoked by the
15620 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74   library.** in t
15630 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69  hree separate ci
15640 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65  rcumstances, ide
15650 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76  ntified by the v
15660 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74  alue passed as t
15670 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72  he.** fourth par
15680 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66  ameter. If the f
15690 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
156a0 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64  is 0, then the d
156b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
156c0 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  on.** passed as 
156d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
156e0 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65  ent has just bee
156f0 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68  n opened. The th
15700 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
15710 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66  points to a buff
15720 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  er containing th
15730 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61  e name of the ma
15740 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
15750 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72  . If the.** four
15760 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15770 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
15780 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74  statement that t
15790 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
157a0 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  er.** points to 
157b0 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78  has just been ex
157c0 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74  ecuted. Or, if t
157d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
157e0 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a  ter is 2, then.*
157f0 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  * the connection
15800 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73   being passed as
15810 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
15820 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63  meter is being c
15830 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68  losed. The.** th
15840 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
15850 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20   passed NULL In 
15860 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65  this case.  An e
15870 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20  xample of using 
15880 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  this.** configur
15890 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e  ation option can
158a0 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20   be seen in the 
158b0 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20  "test_sqllog.c" 
158c0 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a  source file in.*
158d0 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20  * the canonical 
158e0 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72  SQLite source tr
158f0 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ee.</dd>.**.** [
15900 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15910 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64  MAP_SIZE]].** <d
15920 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15930 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64  MMAP_SIZE.** <dd
15940 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  >^SQLITE_CONFIG_
15950 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20  MMAP_SIZE takes 
15960 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67  two 64-bit integ
15970 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36  er (sqlite3_int6
15980 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  4) values.** tha
15990 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c  t are the defaul
159a0 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  t mmap size limi
159b0 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73  t (the default s
159c0 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50  etting for.** [P
159d0 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
159e0 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  ) and the maximu
159f0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15a00 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54  ize limit..** ^T
15a10 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69  he default setti
15a20 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  ng can be overri
15a30 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74  dden by each dat
15a40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15a50 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72   using.** either
15a60 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61   the [PRAGMA mma
15a70 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c  p_size] command,
15a80 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65   or by using the
15a90 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
15aa0 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
15ab0 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68  e control.  ^(Th
15ac0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
15ad0 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77  d mmap size.** w
15ae0 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79 20  ill be silently 
15af0 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65 63  truncated if nec
15b00 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20 69  essary so that i
15b10 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65 65  t does not excee
15b20 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d the.** compile
15b30 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15b40 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15b50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
15b60 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
15b70 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15b80 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
15b90 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
15ba0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
15bb0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15bc0 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15bd0 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15be0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15bf0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15c00 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15c10 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15c20 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15c30 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15c40 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15c50 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15c60 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20  HEAPSIZE option 
15c70 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15c80 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a 2a  e if SQLite is.*
15c90 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57  * compiled for W
15ca0 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65 20  indows with the 
15cb0 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  [SQLITE_WIN32_MA
15cc0 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOC] pre-proces
15cd0 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66  sor macro.** def
15ce0 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f  ined. ^SQLITE_CO
15cf0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
15d00 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d 62  IZE takes a 32-b
15d10 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
15d20 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61  ger value.** tha
15d30 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
15d40 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
15d50 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61 70  the created heap
15d60 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15d70 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15d80 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  DRSZ]].** <dt>SQ
15d90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
15da0 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e  HE_HDRSZ.** <dd>
15db0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15dc0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
15dd0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15de0 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
15df0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
15e00 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15e10 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20 69  ger and writes i
15e20 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
15e30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65   the number of e
15e40 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70 65  xtra.** bytes pe
15e50 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64 20  r page required 
15e60 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69 6e  for each page in
15e70 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
15e80 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
15e90 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74  he amount of ext
15ea0 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72 65  ra space require
15eb0 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65 70  d can change dep
15ec0 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
15ed0 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65  mpiler,.** targe
15ee0 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20  t platform, and 
15ef0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a  SQLite version..
15f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15f10 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a  ONFIG_PMASZ]].**
15f20 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15f30 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e  IG_PMASZ.** <dd>
15f40 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
15f50 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20  IG_PMASZ option 
15f60 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
15f70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
15f80 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  * is an unsigned
15f90 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65 74   integer and set
15fa0 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50  s the "Minimum P
15fb0 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68 65  MA Size" for the
15fc0 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a 2a   multithreaded.*
15fd0 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61 74  * sorter to that
15fe0 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20 64   integer.  The d
15ff0 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50  efault minimum P
16000 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20 62  MA Size is set b
16010 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  y the.** [SQLITE
16020 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63  _SORTER_PMASZ] c
16030 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16040 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64 73  on.  New threads
16050 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a   are launched.**
16060 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73 6f   to help with so
16070 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77 68  rt operations wh
16080 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64  en multithreaded
16090 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65   sorting.** is e
160a0 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74 68  nabled (using th
160b0 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61 64  e [PRAGMA thread
160c0 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20  s] command) and 
160d0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f  the amount of co
160e0 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73  ntent.** to be s
160f0 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74 68  orted exceeds th
16100 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d 65  e page size time
16110 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66  s the minimum of
16120 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20   the.** [PRAGMA 
16130 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74 74  cache_size] sett
16140 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61 6c  ing and this val
16150 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ue..** </dl>.*/.
16160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16170 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
16180 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f  AD  1  /* nil */
16190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
161a0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
161b0 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a  AD   2  /* nil *
161c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
161d0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
161e0 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20  ED    3  /* nil 
161f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16200 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
16210 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c         4  /* sql
16220 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
16230 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16240 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
16250 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73  LLOC     5  /* s
16260 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
16270 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
16280 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16290 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a  ATCH       6  /*
162a0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
162b0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
162c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
162d0 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20  AGECACHE     7  
162e0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
162f0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
16300 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16310 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38  _HEAP          8
16320 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
16330 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a  nByte, int min *
16340 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16350 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
16360 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c  S     9  /* bool
16370 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ean */.#define S
16380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16390 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a  EX        10  /*
163a0 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
163b0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
163c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
163d0 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31  _GETMUTEX     11
163e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74    /* sqlite3_mut
163f0 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f  ex_methods* */./
16400 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c  * previously SQL
16410 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b  ITE_CONFIG_CHUNK
16420 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69  ALLOC 12 which i
16430 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f  s now unused. */
16440 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45   .#define SQLITE
16450 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16460 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20  E    13  /* int 
16470 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16490 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a  CHE       14  /*
164a0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
164b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
164c0 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35 20  GETPCACHE    15 
164d0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
164e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
164f0 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20  IG_LOG          
16500 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f  16  /* xFunc, vo
16510 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  id* */.#define S
16520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
16530 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a            17  /*
16540 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
16550 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16560 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20 2f  ACHE2      18  /
16570 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
16580 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
16590 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
165a0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 20  FIG_GETPCACHE2  
165b0 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   19  /* sqlite3_
165c0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
165d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
165e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
165f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32 30  NG_INDEX_SCAN 20
16600 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66    /* int */.#def
16610 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16620 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20 32  G_SQLLOG       2
16630 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76  1  /* xSqllog, v
16640 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16650 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
16660 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20 2f  AP_SIZE    22  /
16670 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  * sqlite3_int64,
16680 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a   sqlite3_int64 *
16690 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166a0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
166b0 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20 20  APSIZE      23  
166c0 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a  /* int nByte */.
166d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
166e0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
166f0 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f 2a  SZ        24  /*
16700 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65   int *psz */.#de
16710 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16720 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20 20  IG_PMASZ        
16730 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75 6e         25  /* un
16740 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61  signed int szPma
16750 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
16760 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
16770 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75  nnection Configu
16780 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
16790 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
167a0 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
167b0 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
167c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
167d0 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
167e0 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
167f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
16800 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
16810 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
16820 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
16830 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
16840 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
16850 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
16860 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
16870 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
16880 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16890 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
168a0 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
168b0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
168c0 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
168d0 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
168e0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
168f0 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73  fig()] to make s
16900 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ure that.** the 
16910 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54  call worked.  ^T
16920 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
16930 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
16940 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
16950 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
16960 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
16970 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
16980 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
16990 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
169a0 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
169b0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74  *.** <dl>.** <dt
169c0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
169d0 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a  _LOOKASIDE</dt>.
169e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
169f0 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65  tion takes three
16a00 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
16a10 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
16a20 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f  mine the .** [lo
16a30 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
16a40 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67  llocator] config
16a50 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20  uration for the 
16a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16a70 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66  tion]..** ^The f
16a80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74  irst argument (t
16a90 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
16aa0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  er to [sqlite3_d
16ab0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61  b_config()] is a
16ac0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
16ad0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
16ae0 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73  o use for lookas
16af0 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e  ide memory..** ^
16b00 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16b10 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c  nt after the SQL
16b20 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16b30 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d  KASIDE verb.** m
16b40 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68  ay be NULL in wh
16b50 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20  ich case SQLite 
16b60 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68  will allocate th
16b70 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62  e.** lookaside b
16b80 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69  uffer itself usi
16b90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ng [sqlite3_mall
16ba0 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f  oc()]. ^The seco
16bb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
16bc0 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
16bd0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
16be0 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20  fer slot.  ^The 
16bf0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
16c00 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  s the number of.
16c10 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73  ** slots.  The s
16c20 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
16c30 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  r in the first a
16c40 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20  rgument must be 
16c50 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20  greater than.** 
16c60 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20  or equal to the 
16c70 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73  product of the s
16c80 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20  econd and third 
16c90 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20  arguments.  The 
16ca0 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62  buffer.** must b
16cb0 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16cc0 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e  8-byte boundary.
16cd0 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64    ^If the second
16ce0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
16cf0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16d00 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74  LOOKASIDE is not
16d10 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38   a multiple of 8
16d20 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c  , it is internal
16d30 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f  ly.** rounded do
16d40 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73  wn to the next s
16d50 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20  maller multiple 
16d60 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f  of 8.  ^(The loo
16d70 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a  kaside memory.**
16d80 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
16d90 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  or a database co
16da0 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c  nnection can onl
16db0 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65  y be changed whe
16dc0 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63  n that.** connec
16dd0 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72  tion is not curr
16de0 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b  ently using look
16df0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72  aside memory, or
16e00 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a   in other words.
16e10 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72  ** when the "cur
16e20 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75  rent value" retu
16e30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
16e40 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44  te3_db_status](D
16e50 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ,[SQLITE_CONFIG_
16e60 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20  LOOKASIDE],...) 
16e70 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20  is zero..** Any 
16e80 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67  attempt to chang
16e90 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  e the lookaside 
16ea0 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61  memory configura
16eb0 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73  tion when lookas
16ec0 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73  ide.** memory is
16ed0 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74   in use leaves t
16ee0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
16ef0 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72   unchanged and r
16f00 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49  eturns .** [SQLI
16f10 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e  TE_BUSY].)^</dd>
16f20 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
16f30 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
16f40 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_FKEY</dt>.** <
16f50 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
16f60 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
16f70 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
16f80 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66  e enforcement of
16f90 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
16fa0 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20   constraints].  
16fb0 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
16fc0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
16fd0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
16fe0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
16ff0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
17000 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
17010 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
17020 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  nt,.** positive 
17030 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66  to enable FK enf
17040 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61  orcement or nega
17050 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b  tive to leave FK
17060 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20   enforcement.** 
17070 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
17080 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
170a0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
170b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
170c0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
170d0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
170e0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69  FK enforcement i
170f0 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66  s off or on.** f
17100 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
17110 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
17120 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
17130 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
17140 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
17150 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65  e the FK enforce
17160 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20  ment setting is 
17170 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17180 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17190 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
171a0 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
171b0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  R</dt>.** <dd> ^
171c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
171d0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
171e0 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45   disable [CREATE
171f0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
17200 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73  ers]..** There s
17210 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17220 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17230 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17240 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
17250 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
17260 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69  0 to disable tri
17270 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69  ggers,.** positi
17280 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69  ve to enable tri
17290 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76  ggers or negativ
172a0 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73  e to leave the s
172b0 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64  etting unchanged
172c0 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
172d0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
172e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
172f0 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17300 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17310 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17320 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72   whether trigger
17330 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f  s are disabled o
17340 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c  r enabled.** fol
17350 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
17360 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
17370 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
17380 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
17390 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
173a0 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74  the trigger sett
173b0 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
173c0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
173d0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
173e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
173f0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17400 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20         1001  /* 
17410 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
17420 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17430 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
17440 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f  FKEY     1002  /
17450 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
17460 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
17470 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49  ONFIG_ENABLE_TRI
17480 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69  GGER  1003  /* i
17490 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a  nt int* */.../*.
174a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
174b0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45  ble Or Disable E
174c0 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43  xtended Result C
174d0 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  odes.** METHOD: 
174e0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
174f0 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  he sqlite3_exten
17500 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
17510 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  () routine enabl
17520 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
17530 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  he.** [extended 
17540 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65  result codes] fe
17550 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e  ature of SQLite.
17560 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72   ^The extended r
17570 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61  esult.** codes a
17580 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
17590 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f  efault for histo
175a0 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c  rical compatibil
175b0 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ity..*/.SQLITE_A
175c0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
175d0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78  DCALL sqlite3_ex
175e0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
175f0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
17600 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
17610 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
17620 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20  Insert Rowid.** 
17630 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
17640 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72  **.** ^Each entr
17650 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65  y in most SQLite
17660 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20   tables (except 
17670 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  for [WITHOUT ROW
17680 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68  ID] tables).** h
17690 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62  as a unique 64-b
176a0 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74  it signed.** int
176b0 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20  eger key called 
176c0 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f  the [ROWID | "ro
176d0 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69  wid"]. ^The rowi
176e0 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69  d is always avai
176f0 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75  lable.** as an u
17700 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e  ndeclared column
17710 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49   named ROWID, OI
17720 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73  D, or _ROWID_ as
17730 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a   long as those.*
17740 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20  * names are not 
17750 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70  also used by exp
17760 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
17770 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a   columns. ^If.**
17780 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61   the table has a
17790 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20   column of type 
177a0 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59  [INTEGER PRIMARY
177b0 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20   KEY] then that 
177c0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f  column.** is ano
177d0 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74  ther alias for t
177e0 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20  he rowid..**.** 
177f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73  ^The sqlite3_las
17800 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
17810 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
17820 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  rns the [rowid] 
17830 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20  of the .** most 
17840 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75  recent successfu
17850 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
17860 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72  a rowid table or
17870 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
17880 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20  .** on database 
17890 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a  connection D..**
178a0 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b   ^Inserts into [
178b0 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
178c0 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65  ables are not re
178d0 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e  corded..** ^If n
178e0 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  o successful [IN
178f0 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69  SERT]s into rowi
17900 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65  d tables.** have
17910 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f   ever occurred o
17920 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
17930 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a  onnection D, .**
17940 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
17950 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17960 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  D) returns zero.
17970 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
17980 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
17990 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
179a0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
179b0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
179c0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
179d0 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
179e0 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
179f0 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
17a00 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
17a10 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
17a20 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
17a30 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
17a40 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
17a50 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
17a60 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
17a70 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
17a80 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
17a90 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
17aa0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
17ab0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
17ac0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17ad0 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
17ae0 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
17af0 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
17b00 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
17b10 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
17b20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
17b30 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
17b40 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
17b50 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
17b60 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17b70 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
17b80 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
17b90 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
17ba0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
17bb0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
17bc0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
17bd0 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
17be0 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
17bf0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
17c00 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
17c10 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
17c20 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
17c30 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
17c40 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
17c50 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
17c60 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
17c70 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
17c80 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
17c90 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
17ca0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
17cb0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
17cc0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
17cd0 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
17ce0 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
17cf0 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
17d00 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
17d10 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
17d20 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
17d30 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
17d40 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
17d50 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
17d60 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
17d70 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
17d80 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
17d90 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
17da0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
17db0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
17dc0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
17dd0 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
17de0 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
17df0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17e00 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17e10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17e20 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
17e30 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
17e40 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
17e50 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17e60 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
17e70 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
17e80 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
17e90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
17ea0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
17eb0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
17ec0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
17ed0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
17ee0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
17ef0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17f00 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
17f10 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
17f20 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
17f30 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
17f40 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
17f50 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
17f60 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  owid]..*/.SQLITE
17f70 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
17f80 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
17f90 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  L sqlite3_last_i
17fa0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
17fb0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
17fc0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
17fd0 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
17fe0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
17ff0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18000 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18010 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
18020 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
18030 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
18040 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
18050 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18060 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
18070 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
18080 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
18090 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
180a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
180b0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
180c0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
180d0 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
180e0 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
180f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
18100 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
18110 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
18120 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
18130 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
18140 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
18150 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
18160 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18170 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18180 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
18190 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
181a0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
181b0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
181c0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
181d0 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
181e0 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
181f0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
18200 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
18210 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
18220 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
18230 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
18240 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
18250 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
18260 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
18270 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
18280 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
18290 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
182a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
182b0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
182c0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
182d0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
182e0 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
182f0 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
18300 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
18310 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
18320 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
18330 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
18340 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
18350 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
18360 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
18370 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
18380 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
18390 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
183a0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
183b0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
183c0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
183d0 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
183e0 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
183f0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
18400 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
18410 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
18420 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
18430 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18440 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
18450 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
18460 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
18470 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
18480 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18490 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
184a0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
184b0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
184c0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
184d0 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
184e0 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
184f0 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
18500 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
18510 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
18520 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
18530 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
18540 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
18550 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
18560 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
18570 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
18580 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
18590 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
185a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
185b0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
185c0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
185d0 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
185e0 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
185f0 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
18600 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
18610 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
18620 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
18630 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
18640 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
18650 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
18660 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
18670 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
18680 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
18690 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
186a0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
186b0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
186c0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
186d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
186e0 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
186f0 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
18700 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
18710 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
18720 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
18730 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
18740 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
18750 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
18760 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
18770 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
18780 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
18790 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
187a0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
187b0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
187c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
187d0 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
187e0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
187f0 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
18800 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
18810 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
18820 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
18830 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
18840 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
18850 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
18860 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
18870 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
18880 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18890 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
188a0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
188b0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
188c0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
188d0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
188e0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
188f0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
18900 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
18910 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
18920 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
18930 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
18940 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18950 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
18960 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
18970 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18980 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18990 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
189a0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
189b0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
189c0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
189d0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61  * CAPI3REF: Tota
189e0 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  l Number Of Rows
189f0 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
18a00 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18a10 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18a20 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f  n returns the to
18a30 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  tal number of ro
18a40 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64  ws inserted, mod
18a50 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  ified or.** dele
18a60 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45  ted by all [INSE
18a70 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72  RT], [UPDATE] or
18a80 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
18a90 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a  ents completed.*
18aa0 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61  * since the data
18ab0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18ac0 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c  was opened, incl
18ad0 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63  uding those exec
18ae0 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20  uted as.** part 
18af0 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  of trigger progr
18b00 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20  ams. ^Executing 
18b10 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f  any other type o
18b20 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a  f SQL statement.
18b30 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65  ** does not affe
18b40 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ct the value ret
18b50 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18b60 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
18b70 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65  ..** .** ^Change
18b80 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f  s made as part o
18b90 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  f [foreign key a
18ba0 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c  ctions] are incl
18bb0 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63  uded in the.** c
18bc0 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20  ount, but those 
18bd0 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20  made as part of 
18be0 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69  REPLACE constrai
18bf0 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72  nt resolution ar
18c00 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67  e.** not. ^Chang
18c10 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
18c20 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65  t are intercepte
18c30 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20  d by INSTEAD OF 
18c40 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65  triggers .** are
18c50 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   not counted..**
18c60 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68   .** See also th
18c70 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
18c80 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
18c90 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
18ca0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
18cb0 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
18cc0 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
18cd0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
18ce0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
18cf0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
18d00 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
18d10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18d20 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
18d30 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
18d40 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
18d50 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
18d60 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
18d70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
18d80 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
18d90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
18da0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
18db0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18dc0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
18dd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18de0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
18df0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
18e00 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18e10 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18e20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
18e30 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
18e40 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
18e50 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
18e60 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
18e70 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
18e80 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
18e90 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
18ea0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
18eb0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
18ec0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
18ed0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
18ee0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
18ef0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
18f00 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
18f10 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
18f20 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
18f30 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
18f40 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
18f50 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
18f60 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
18f70 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
18f80 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
18f90 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
18fa0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
18fb0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
18fc0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
18fd0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
18fe0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
18ff0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
19000 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
19010 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
19020 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
19030 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
19040 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
19050 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
19060 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
19070 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
19080 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
19090 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
190a0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
190b0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
190c0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
190d0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
190e0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
190f0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
19100 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
19110 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
19120 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
19130 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
19140 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
19150 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
19160 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
19170 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
19180 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
19190 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
191a0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
191b0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
191c0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
191d0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
191e0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
191f0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
19200 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
19210 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
19220 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
19230 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
19240 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
19250 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
19260 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
19270 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
19280 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
19290 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
192a0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
192b0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
192c0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
192d0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
192e0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
192f0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
19300 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
19310 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
19320 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
19330 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
19340 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
19350 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
19360 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
19370 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
19380 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
19390 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
193a0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
193b0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
193c0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
193d0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
193e0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
193f0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
19400 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
19410 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
19420 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
19430 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
19440 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
19450 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
19460 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
19470 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19480 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19490 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
194a0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
194b0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
194c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
194d0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
194e0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
194f0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
19500 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
19510 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
19520 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
19530 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
19540 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
19550 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
19560 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19570 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
19580 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
19590 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
195a0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
195b0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
195c0 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
195d0 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
195e0 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
195f0 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
19600 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
19610 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
19620 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
19630 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
19640 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
19650 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
19660 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
19670 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
19680 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
19690 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
196a0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
196b0 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
196c0 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
196d0 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
196e0 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
196f0 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
19700 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
19710 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
19720 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
19730 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
19740 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
19750 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
19760 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
19770 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
19780 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
19790 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
197a0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
197b0 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
197c0 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
197d0 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
197e0 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
197f0 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
19800 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
19810 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
19820 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
19830 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19840 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
19850 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
19860 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
19870 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
19880 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
19890 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
198a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
198b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
198c0 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
198d0 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
198e0 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
198f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
19900 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
19910 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
19920 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
19930 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
19940 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
19950 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
19960 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
19970 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
19980 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
19990 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
199a0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
199b0 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
199c0 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
199d0 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
199e0 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
199f0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19a00 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
19a10 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
19a20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
19a30 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
19a40 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19a50 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
19a60 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
19a70 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
19a80 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
19a90 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19aa0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
19ab0 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
19ac0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
19ad0 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
19ae0 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
19af0 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
19b00 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
19b10 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
19b20 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
19b30 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
19b40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
19b50 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19b60 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
19b70 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
19b80 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
19b90 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
19ba0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
19bb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19bc0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
19bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19be0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
19bf0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
19c00 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
19c10 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
19c20 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20  te16(const void 
19c30 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  *sql);../*.** CA
19c40 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72  PI3REF: Register
19c50 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48   A Callback To H
19c60 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53  andle SQLITE_BUS
19c70 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57  Y Errors.** KEYW
19c80 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64  ORDS: {busy-hand
19c90 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62  ler callback} {b
19ca0 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20  usy handler}.** 
19cb0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
19cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19cd0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19ce0 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73  D,X,P) routine s
19cf0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
19d00 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61  unction X.** tha
19d10 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
19d20 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ed with argument
19d30 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61   P whenever.** a
19d40 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
19d50 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61  e to access a da
19d60 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73  tabase table ass
19d70 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
19d80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
19d90 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f  tion] D when ano
19da0 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f  ther thread.** o
19db0 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68  r process has th
19dc0 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a  e table locked..
19dd0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62  ** The sqlite3_b
19de0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e  usy_handler() in
19df0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
19e00 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20  to implement.** 
19e10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19e20 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52  meout()] and [PR
19e30 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
19e40 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  t]..**.** ^If th
19e50 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
19e60 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
19e70 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69  QLITE_BUSY].** i
19e80 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
19e90 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f  iately upon enco
19ea0 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63  untering the loc
19eb0 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79  k.  ^If the busy
19ec0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
19ed0 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  not NULL, then t
19ee0 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68  he callback migh
19ef0 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  t be invoked wit
19f00 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e  h two arguments.
19f10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
19f20 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
19f30 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
19f40 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
19f50 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68  void* pointer wh
19f60 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68  ich.** is the th
19f70 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
19f80 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
19f90 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65  dler().  ^The se
19fa0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
19fb0 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
19fc0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  dler callback is
19fd0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74   the number of t
19fe0 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75  imes that the bu
19ff0 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a  sy handler has.*
1a000 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70  * been invoked p
1a010 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68  reviously for th
1a020 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65  e same locking e
1a030 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1a040 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1a050 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1a060 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1a070 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1a080 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1a090 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1a0a0 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72  QLITE_BUSY] is r
1a0b0 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68  eturned.** to th
1a0c0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a  e application..*
1a0d0 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1a0e0 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1a0f0 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1a100 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1a110 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74  made to access t
1a120 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1a130 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1a140 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1a150 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1a160 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1a170 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1a180 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1a190 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1a1a0 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1a1b0 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1a1c0 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1a1d0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1a1e0 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1a1f0 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1a200 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1a210 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1a220 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1a230 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  Y].** to the app
1a240 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64  lication instead
1a250 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1a260 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65   .** busy handle
1a270 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61  r..** Consider a
1a280 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20   scenario where 
1a290 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68  one process is h
1a2a0 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f  olding a read lo
1a2b0 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73  ck that.** it is
1a2c0 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f   trying to promo
1a2d0 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64  te to a reserved
1a2e0 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73   lock and.** a s
1a2f0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73  econd process is
1a300 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72   holding a reser
1a310 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74  ved lock that it
1a320 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f   is trying.** to
1a330 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65   promote to an e
1a340 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20  xclusive lock.  
1a350 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  The first proces
1a360 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64  s cannot proceed
1a370 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69  .** because it i
1a380 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1a390 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20   second and the 
1a3a0 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63  second process c
1a3b0 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64  annot.** proceed
1a3c0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1a3d0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69  locked by the fi
1a3e0 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72  rst.  If both pr
1a3f0 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b  ocesses.** invok
1a400 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  e the busy handl
1a410 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c  ers, neither wil
1a420 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72  l make any progr
1a430 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c  ess.  Therefore,
1a440 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72  .** SQLite retur
1a450 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ns [SQLITE_BUSY]
1a460 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70   for the first p
1a470 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74  rocess, hoping t
1a480 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c  hat this.** will
1a490 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73   induce the firs
1a4a0 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c  t process to rel
1a4b0 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f  ease its read lo
1a4c0 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20  ck and allow.** 
1a4d0 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
1a4e0 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a  ss to proceed..*
1a4f0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
1a500 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  t busy callback 
1a510 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  is NULL..**.** ^
1a520 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
1a530 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
1a540 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
1a550 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
1a560 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a570 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
1a580 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
1a590 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
1a5a0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
1a5b0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
1a5c0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
1a5d0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1a5e0 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75  t()].** or evalu
1a5f0 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75  ating [PRAGMA bu
1a600 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69  sy_timeout=N] wi
1a610 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a  ll change the.**
1a620 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e   busy handler an
1a630 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79  d thus clear any
1a640 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20   previously set 
1a650 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a660 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c  .** The busy cal
1a670 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74  lback should not
1a680 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e   take any action
1a690 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74  s which modify t
1a6a0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
1a6b0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1a6c0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a6d0 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68  handler.  In oth
1a6e0 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65  er words,.** the
1a6f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a700 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20   not reentrant. 
1a710 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
1a720 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
1a730 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
1a740 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
1a750 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
1a760 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
1a770 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1a780 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
1a790 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
1a7a0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1a7b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
1a7c0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1a7d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1a7e0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1a7f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
1a800 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
1a810 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1a820 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
1a830 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48   Timeout.** METH
1a840 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1a850 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a860 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1a870 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1a880 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1a890 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1a8a0 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1a8b0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1a8c0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1a8d0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1a8e0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1a8f0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1a900 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1a910 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1a920 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1a930 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1a940 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1a950 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1a960 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1a970 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1a980 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1a990 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1a9a0 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1a9b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1a9c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
1a9d0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
1a9e0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
1a9f0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
1aa00 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
1aa10 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
1aa20 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
1aa30 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1aa40 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1aa50 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
1aa60 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1aa70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1aa80 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65  ion] at any give
1aa90 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1aaa0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1aab0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1aac0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1aad0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1aae0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1aaf0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1ab00 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1ab10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1ab20 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a   cleared.)^.**.*
1ab30 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52  * See also:  [PR
1ab40 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1ab50 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t].*/.SQLITE_API
1ab60 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1ab70 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1ab80 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1ab90 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1aba0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1abb0 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1abc0 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1abd0 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eries.** METHOD:
1abe0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
1abf0 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
1ac00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
1ac10 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
1ac20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1ac30 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
1ac40 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1ac50 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
1ac60 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
1ac70 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
1ac80 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
1ac90 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
1aca0 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
1acb0 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1acc0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
1acd0 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
1ace0 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
1acf0 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
1ad00 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
1ad10 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
1ad20 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
1ad30 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
1ad40 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
1ad50 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
1ad60 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
1ad70 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
1ad80 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
1ad90 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ada0 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
1adb0 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
1adc0 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
1add0 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
1ade0 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
1adf0 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
1ae00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
1ae10 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
1ae20 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
1ae30 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
1ae40 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
1ae50 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
1ae60 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
1ae70 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
1ae80 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
1ae90 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
1aea0 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
1aeb0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1aec0 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
1aed0 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
1aee0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
1aef0 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
1af00 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
1af10 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
1af20 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
1af30 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
1af40 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
1af50 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
1af60 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
1af70 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
1af80 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
1af90 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
1afa0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1afb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
1afc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
1afd0 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
1afe0 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
1aff0 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
1b000 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
1b010 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
1b020 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
1b030 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
1b040 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b050 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1b060 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
1b070 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
1b080 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b090 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
1b0a0 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
1b0b0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1b0c0 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
1b0d0 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
1b0e0 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
1b0f0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1b100 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1b110 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
1b120 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
1b130 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b140 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
1b150 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
1b160 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
1b170 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
1b180 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
1b190 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
1b1a0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1b1b0 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
1b1c0 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
1b1d0 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
1b1e0 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
1b1f0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
1b200 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
1b210 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
1b220 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
1b230 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
1b240 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
1b250 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
1b260 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
1b270 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
1b280 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b290 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b2a0 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1b2b0 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1b2c0 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1b2d0 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1b2e0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1b2f0 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1b300 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b310 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1b320 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b330 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1b340 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b350 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1b360 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b370 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1b380 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1b390 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1b3a0 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1b3b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b3c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1b3d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b3e0 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1b3f0 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1b400 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1b410 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1b420 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1b430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1b440 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1b450 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1b460 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1b470 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1b480 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1b490 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1b4a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1b4b0 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1b4c0 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1b4d0 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1b4e0 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1b4f0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1b500 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1b510 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1b520 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1b530 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1b540 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1b550 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1b560 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1b570 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1b580 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1b590 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1b5a0 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1b5b0 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1b5c0 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1b5d0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1b5e0 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1b5f0 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1b600 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1b610 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1b620 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1b630 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1b640 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1b650 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1b660 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1b670 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1b680 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1b690 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1b6a0 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1b6b0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b6c0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1b6d0 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1b6e0 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1b6f0 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1b700 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1b710 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1b720 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1b730 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1b740 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1b750 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1b760 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1b770 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1b780 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1b790 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1b7a0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1b7b0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1b7c0 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1b7d0 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1b7e0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1b7f0 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1b800 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1b810 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1b820 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1b830 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
1b840 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1b850 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
1b860 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
1b870 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
1b880 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
1b890 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
1b8a0 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
1b8b0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
1b8c0 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
1b8d0 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
1b8e0 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
1b8f0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
1b900 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1b910 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
1b920 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
1b930 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
1b940 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1b950 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
1b960 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
1b970 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
1b980 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
1b990 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1b9a0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .);.SQLITE_API v
1b9b0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1b9c0 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  LL sqlite3_free_
1b9d0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1b9e0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1b9f0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1ba00 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1ba10 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1ba20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ba30 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1ba40 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1ba50 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1ba60 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1ba70 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1ba80 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72  rary..** These r
1ba90 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61  outines understa
1baa0 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63  nd most of the c
1bab0 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74  ommon K&R format
1bac0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a  ting options,.**
1bad0 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74   plus some addit
1bae0 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61  ional non-standa
1baf0 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61  rd formats, deta
1bb00 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e  iled below..** N
1bb10 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66  ote that some of
1bb20 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72   the more obscur
1bb30 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  e formatting opt
1bb40 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74  ions from recent
1bb50 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74  .** C-library st
1bb60 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74  andards are omit
1bb70 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d  ted from this im
1bb80 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a  plementation..**
1bb90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bba0 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73  _mprintf() and s
1bbb0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1bbc0 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65  ) routines write
1bbd0 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74   their.** result
1bbe0 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  s into memory ob
1bbf0 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
1bc00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a  ite3_malloc()]..
1bc10 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72  ** The strings r
1bc20 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1bc30 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68   two routines sh
1bc40 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61  ould be.** relea
1bc50 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
1bc60 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20  free()].  ^Both 
1bc70 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1bc80 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
1bc90 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  r if [sqlite3_ma
1bca0 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c  lloc()] is unabl
1bcb0 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e  e to allocate en
1bcc0 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74  ough.** memory t
1bcd0 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c  o hold the resul
1bce0 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  ting string..**.
1bcf0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1bd00 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _snprintf() rout
1bd10 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ine is similar t
1bd20 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66  o "snprintf()" f
1bd30 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64  rom.** the stand
1bd40 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20  ard C library.  
1bd50 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72  The result is wr
1bd60 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a  itten into the.*
1bd70 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65  * buffer supplie
1bd80 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1bd90 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20  parameter whose 
1bda0 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79  size is given by
1bdb0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61  .** the first pa
1bdc0 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68  rameter. Note th
1bdd0 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20  at the order of 
1bde0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f  the.** first two
1bdf0 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72   parameters is r
1be00 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70  eversed from snp
1be10 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73  rintf().)^  This
1be20 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72   is an.** histor
1be30 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68  ical accident th
1be40 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78  at cannot be fix
1be50 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
1be60 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ing.** backwards
1be70 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20   compatibility. 
1be80 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61   ^(Note also tha
1be90 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  t sqlite3_snprin
1bea0 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20  tf().** returns 
1beb0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73  a pointer to its
1bec0 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20   buffer instead 
1bed0 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  of the number of
1bee0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61  .** characters a
1bef0 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20  ctually written 
1bf00 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e  into the buffer.
1bf10 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61  )^  We admit tha
1bf20 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  t.** the number 
1bf30 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72  of characters wr
1bf40 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61  itten would be a
1bf50 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74   more useful ret
1bf60 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74  urn.** value but
1bf70 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67   we cannot chang
1bf80 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  e the implementa
1bf90 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
1bfa0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f  snprintf().** no
1bfb0 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  w without breaki
1bfc0 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ng compatibility
1bfd0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67  ..**.** ^As long
1bfe0 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73   as the buffer s
1bff0 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74  ize is greater t
1c000 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65  han zero, sqlite
1c010 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1c020 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
1c030 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c  the buffer is al
1c040 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
1c050 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73  ated.  ^The firs
1c060 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22  t.** parameter "
1c070 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20  n" is the total 
1c080 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
1c090 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70  er, including sp
1c0a0 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a  ace for.** the z
1c0b0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1c0c0 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20   So the longest 
1c0d0 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20  string that can 
1c0e0 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a  be completely.**
1c0f0 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65   written will be
1c100 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e   n-1 characters.
1c110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1c120 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20  te3_vsnprintf() 
1c130 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72  routine is a var
1c140 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20  args version of 
1c150 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1c160 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ()..**.** These 
1c170 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70  routines all imp
1c180 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69  lement some addi
1c190 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e  tional formattin
1c1a0 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61  g.** options tha
1c1b0 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72  t are useful for
1c1c0 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51   constructing SQ
1c1d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1c1e0 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61   All of the usua
1c1f0 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61  l printf() forma
1c200 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70  tting options ap
1c210 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f  ply.  In additio
1c220 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61  n, there.** is a
1c230 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22  re "%q", "%Q", "
1c240 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74  %w" and "%z" opt
1c250 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ions..**.** ^(Th
1c260 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %q option work
1c270 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61  s like %s in tha
1c280 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73  t it substitutes
1c290 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
1c2a0 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d  d.** string from
1c2b0 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69   the argument li
1c2c0 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f  st.  But %q also
1c2d0 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27   doubles every '
1c2e0 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  \'' character..*
1c2f0 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64  * %q is designed
1c300 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20   for use inside 
1c310 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1c320 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67  .)^  By doubling
1c330 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68   each '\''.** ch
1c340 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70  aracter it escap
1c350 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65  es that characte
1c360 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20  r and allows it 
1c370 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69  to be inserted i
1c380 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  nto.** the strin
1c390 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61  g..**.** For exa
1c3a0 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65  mple, assume the
1c3b0 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65   string variable
1c3c0 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20   zText contains 
1c3d0 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  text as follows:
1c3e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1c3f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1c400 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73  r *zText = "It's
1c410 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a   a happy day!";.
1c420 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c430 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65  quote>.**.** One
1c440 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65   can use this te
1c450 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  xt in an SQL sta
1c460 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77  tement as follow
1c470 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c480 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1c490 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1c4a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1c4b0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1c4c0 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54  ALUES('%q')", zT
1c4d0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
1c4e0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
1c4f0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
1c500 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
1c510 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c520 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c530 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66  Because the %q f
1c540 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20  ormat string is 
1c550 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63  used, the '\'' c
1c560 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78  haracter in zTex
1c570 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20  t.** is escaped 
1c580 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65  and the SQL gene
1c590 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c  rated is as foll
1c5a0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1c5b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1c5c0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1c5d0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27  le1 VALUES('It''
1c5e0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
1c5f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1c600 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1c610 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20  is is correct.  
1c620 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69  Had we used %s i
1c630 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68  nstead of %q, th
1c640 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a  e generated SQL.
1c650 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f  ** would have lo
1c660 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a  oked like this:.
1c670 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1c680 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45  e><pre>.**  INSE
1c690 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56  RT INTO table1 V
1c6a0 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61  ALUES('It's a ha
1c6b0 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c  ppy day!');.** <
1c6c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c6d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65  e>.**.** This se
1c6e0 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20  cond example is 
1c6f0 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72  an SQL syntax er
1c700 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72  ror.  As a gener
1c710 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75  al rule you shou
1c720 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  ld.** always use
1c730 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %q instead of %
1c740 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  s when inserting
1c750 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72   text into a str
1c760 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a  ing literal..**.
1c770 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69  ** ^(The %Q opti
1c780 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71  on works like %q
1c790 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20   except it also 
1c7a0 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74  adds single quot
1c7b0 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65  es around.** the
1c7c0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1c7d0 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41  total string.  A
1c7e0 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
1c7f0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e  the parameter in
1c800 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   the.** argument
1c810 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20   list is a NULL 
1c820 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73  pointer, %Q subs
1c830 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74  titutes the text
1c840 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74   "NULL" (without
1c850 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  .** single quote
1c860 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65  s).)^  So, for e
1c870 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c  xample, one coul
1c880 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  d say:.**.** <bl
1c890 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c8a0 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20  *  char *zSQL = 
1c8b0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1c8c0 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62  "INSERT INTO tab
1c8d0 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20  le VALUES(%Q)", 
1c8e0 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1c8f0 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1c900 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1c910 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1c920 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1c930 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1c940 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65  * The code above
1c950 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63   will render a c
1c960 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65  orrect SQL state
1c970 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c  ment in the zSQL
1c980 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65  .** variable eve
1c990 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76  n if the zText v
1c9a0 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
1c9b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1c9c0 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d   ^(The "%w" form
1c9d0 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73  atting option is
1c9e0 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70   like "%q" excep
1c9f0 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74  t that it expect
1ca00 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61  s to.** be conta
1ca10 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62  ined within doub
1ca20 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61  le-quotes instea
1ca30 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74  d of single quot
1ca40 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73  es, and it.** es
1ca50 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65  capes the double
1ca60 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72  -quote character
1ca70 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1ca80 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20  single-quote.** 
1ca90 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68  character.)^  Th
1caa0 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e  e "%w" formattin
1cab0 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65  g option is inte
1cac0 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20  nded for safely 
1cad0 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62  inserting.** tab
1cae0 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61  le and column na
1caf0 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74  mes into a const
1cb00 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65  ructed SQL state
1cb10 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ment..**.** ^(Th
1cb20 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e  e "%z" formattin
1cb30 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  g option works l
1cb40 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74  ike "%s" but wit
1cb50 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f  h the.** additio
1cb60 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65  n that after the
1cb70 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e   string has been
1cb80 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64   read and copied
1cb90 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73   into.** the res
1cba0 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ult, [sqlite3_fr
1cbb0 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  ee()] is called 
1cbc0 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  on the input str
1cbd0 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  ing.)^.*/.SQLITE
1cbe0 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cbf0 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
1cc00 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1cc10 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
1cc20 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54  _API char *SQLIT
1cc30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1cc40 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1cc50 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1cc60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1cc70 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  r *SQLITE_CDECL 
1cc80 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1cc90 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1cca0 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51   char*, ...);.SQ
1ccb0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 53  LITE_API char *S
1ccc0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1ccd0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1cce0 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1ccf0 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1cd00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1cd10 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1cd20 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1cd30 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1cd40 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1cd50 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1cd60 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1cd70 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1cd80 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1cd90 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1cda0 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1cdb0 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1cdc0 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1cdd0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1cde0 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1cdf0 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1ce00 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1ce10 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1ce20 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1ce30 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1ce40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ce50 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1ce60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1ce70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1ce80 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1ce90 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1cea0 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1ceb0 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1cec0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1ced0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1cee0 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1cef0 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1cf00 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1cf10 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1cf20 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1cf30 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1cf40 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cf50 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1cf60 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1cf70 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1cf80 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1cf90 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
1cfa0 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1cfb0 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77  c64(N) routine w
1cfc0 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a  orks just like.*
1cfd0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1cfe0 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20  (N) except that 
1cff0 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64  N is an unsigned
1d000 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
1d010 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1d020 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e  signed 32-bit in
1d030 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  teger..**.** ^Ca
1d040 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1d050 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1d060 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1d070 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1d080 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1d090 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1d0a0 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1d0b0 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1d0c0 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1d0d0 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1d0e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1d0f0 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1d100 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1d110 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1d120 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1d130 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1d140 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1d150 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1d160 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1d170 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1d180 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1d190 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1d1a0 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1d1b0 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1d1c0 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1d1d0 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1d1e0 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1d1f0 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1d200 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1d210 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1d220 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1d230 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1d240 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1d250 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1d260 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1d270 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1d280 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1d290 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1d2a0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d2b0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1d2c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1d2d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d2e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d2f0 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
1d300 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a  pts to resize a.
1d310 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20  ** prior memory 
1d320 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20  allocation X to 
1d330 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  be at least N by
1d340 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
1d350 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  X parameter to s
1d360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d370 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ,N).** is a NULL
1d380 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
1d390 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
1d3a0 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
1d3b0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
1d3c0 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20  lloc(N)..** ^If 
1d3d0 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20  the N parameter 
1d3e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1d3f0 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20  oc(X,N) is zero 
1d400 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1d410 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1d420 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1d430 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1d440 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1d450 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f  X)..** ^sqlite3_
1d460 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d470 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1d480 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1d490 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1d4a0 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1d4b0 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1d4c0 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d  insufficient mem
1d4d0 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ory is available
1d4e0 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1d4f0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1d500 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1d510 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1d520 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1d530 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1d540 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1d550 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d560 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1d570 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1d580 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74  alloc(X,N) and t
1d590 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1d5a0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1d5b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1d5c0 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1d5d0 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20  s NULL and N is 
1d5e0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74  positive, then t
1d5f0 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f  he.** prior allo
1d600 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72  cation is not fr
1d610 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1d620 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1d630 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  4(X,N) interface
1d640 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65  s works the same
1d650 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   as.** sqlite3_r
1d660 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65  ealloc(X,N) exce
1d670 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36  pt that N is a 6
1d680 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  4-bit unsigned i
1d690 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1d6a0 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69  * of a 32-bit si
1d6b0 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  gned integer..**
1d6c0 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d  .** ^If X is a m
1d6d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d6e0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
1d6f0 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1d700 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73  3_malloc(),.** s
1d710 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28  qlite3_malloc64(
1d720 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
1d730 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  oc(), or sqlite3
1d740 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68  _realloc64(), th
1d750 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73  en.** sqlite3_ms
1d760 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74  ize(X) returns t
1d770 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20  he size of that 
1d780 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d790 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  n in bytes..** ^
1d7a0 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1d7b0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73  ed by sqlite3_ms
1d7c0 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20  ize(X) might be 
1d7d0 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
1d7e0 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74  number.** of byt
1d7f0 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65  es requested whe
1d800 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65  n X was allocate
1d810 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e  d.  ^If X is a N
1d820 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  .** sqlite3_msiz
1d840 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72  e(X) returns zer
1d850 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20  o.  If X points 
1d860 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61  to something tha
1d870 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20  t is not.** the 
1d880 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d  beginning of mem
1d890 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ory allocation, 
1d8a0 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20  or if it points 
1d8b0 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a  to a formerly.**
1d8c0 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c   valid memory al
1d8d0 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61  location that ha
1d8e0 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64  s now been freed
1d8f0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
1d900 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ior.** of sqlite
1d910 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e  3_msize(X) is un
1d920 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73  defined and poss
1d930 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ibly harmful..**
1d940 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1d950 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1d960 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71  te3_malloc(), sq
1d970 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c  lite3_realloc(),
1d980 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1d990 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69  oc64(), and sqli
1d9a0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a  te3_realloc64().
1d9b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1d9c0 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1d9d0 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1d9e0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1d9f0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1da00 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1da10 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1da20 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1da30 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1da40 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1da50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1da60 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1da70 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1da80 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1da90 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1daa0 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1dab0 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1dac0 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1dad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1dae0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1daf0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1db00 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1db10 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1db20 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1db30 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1db40 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1db50 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1db60 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1db70 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1db80 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1db90 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1dba0 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1dbb0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1dbc0 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1dbd0 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1dbe0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1dbf0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1dc00 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1dc10 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1dc20 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1dc30 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1dc40 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1dc50 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1dc60 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1dc70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1dc80 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1dc90 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1dca0 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1dcb0 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1dcc0 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1dcd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1dce0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1dcf0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1dd00 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1dd10 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1dd20 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1dd30 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1dd40 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1dd50 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1dd60 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1dd70 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1dd80 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1dd90 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1dda0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1ddb0 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1ddc0 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1ddd0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1dde0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1ddf0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1de00 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1de10 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1de20 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1de30 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1de40 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1de50 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1de60 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1de70 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
1de80 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1de90 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1dea0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1deb0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1dec0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1ded0 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  L sqlite3_malloc
1dee0 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64(sqlite3_uint6
1def0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1df00 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1df10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ALL sqlite3_real
1df20 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
1df30 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1df40 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1df50 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1df60 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  64(void*, sqlite
1df70 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1df80 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1df90 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1dfa0 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 53  3_free(void*);.S
1dfb0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1dfc0 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45 5f  3_uint64 SQLITE_
1dfd0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1dfe0 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  msize(void*);../
1dff0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1e000 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1e010 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1e020 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1e030 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1e040 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1e050 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1e060 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1e070 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1e080 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1e090 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1e0a0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1e0b0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1e0c0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1e0d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1e0e0 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1e0f0 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1e100 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1e110 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1e120 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1e130 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1e140 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1e150 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1e160 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1e170 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1e180 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1e190 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1e1a0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1e1b0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1e1c0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1e1d0 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1e1e0 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1e1f0 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1e200 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1e210 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1e220 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1e230 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1e240 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e250 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1e260 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1e270 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1e280 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1e290 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1e2a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1e2b0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1e2c0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1e2d0 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1e2e0 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1e2f0 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1e300 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1e310 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1e320 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1e330 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1e340 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1e350 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1e360 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1e370 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1e380 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1e390 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1e3a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1e3b0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1e3c0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1e3d0 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1e3e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1e3f0 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1e400 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1e410 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1e420 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
1e430 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1e440 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  64 SQLITE_STDCAL
1e450 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  L sqlite3_memory
1e460 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c  _used(void);.SQL
1e470 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
1e480 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44  int64 SQLITE_STD
1e490 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d  CALL sqlite3_mem
1e4a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1e4b0 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1e4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1e4d0 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1e4e0 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1e4f0 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1e500 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1e510 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1e520 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1e530 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1e540 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1e550 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1e560 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1e570 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1e580 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1e590 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1e5a0 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1e5b0 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1e5c0 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1e5d0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1e5e0 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1e5f0 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1e600 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1e610 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1e620 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1e630 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1e640 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1e650 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1e660 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1e670 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1e680 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1e690 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1e6a0 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1e6b0 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74  * ^The P paramet
1e6c0 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c  er can be a NULL
1e6d0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e6e0 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ^If this routine
1e6f0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72   has not been pr
1e700 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20  eviously called 
1e710 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f  or if the previo
1e720 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e  us.** call had N
1e730 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f   less than one o
1e740 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
1e750 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65   for P, then the
1e760 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64   PRNG is.** seed
1e770 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1e780 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ess obtained fro
1e790 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1e7a0 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74  s method of.** t
1e7b0 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1e7c0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1e7d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76  .** ^If the prev
1e7e0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69  ious call to thi
1e7f0 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e  s routine had an
1e800 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20   N of 1 or more 
1e810 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c  and a.** non-NUL
1e820 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65  L P then the pse
1e830 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69  udo-randomness i
1e840 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69  s generated.** i
1e850 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69  nternally and wi
1e860 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74  thout recourse t
1e870 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
1e880 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a  fs] xRandomness.
1e890 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51  ** method..*/.SQ
1e8a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51  LITE_API void SQ
1e8b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1e8c0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
1e8d0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
1e8e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e8f0 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
1e900 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
1e910 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
1e920 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1e930 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1e940 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1e950 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1e960 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1e970 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1e980 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1e990 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1e9a0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1e9b0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e9c0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1e9d0 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1e9e0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1e9f0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1ea00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1ea10 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1ea20 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ea30 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1ea40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ea50 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1ea60 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1ea70 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1ea80 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1ea90 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1eaa0 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1eab0 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1eac0 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1ead0 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1eae0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1eaf0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1eb00 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1eb10 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1eb20 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1eb30 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1eb40 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1eb50 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1eb60 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1eb70 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1eb80 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1eb90 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1eba0 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1ebb0 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1ebc0 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1ebd0 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1ebe0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1ebf0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1ec00 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1ec10 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1ec20 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1ec30 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1ec40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ec50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1ec60 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1ec70 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1ec80 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1ec90 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1eca0 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1ecb0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ecc0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1ecd0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1ece0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1ecf0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1ed00 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1ed10 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1ed20 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1ed30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1ed40 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1ed50 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1ed60 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1ed70 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1ed80 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1ed90 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1eda0 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1edb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1edc0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1edd0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1ede0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1edf0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1ee00 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1ee10 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1ee20 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1ee30 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1ee40 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1ee50 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1ee60 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ee70 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1ee80 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1ee90 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1eea0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1eeb0 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1eec0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1eed0 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1eee0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1eef0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1ef00 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1ef10 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1ef20 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1ef30 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1ef40 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1ef50 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1ef60 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1ef70 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1ef80 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1ef90 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1efa0 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1efb0 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1efc0 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1efd0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1efe0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1eff0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1f000 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1f010 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1f020 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1f030 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1f040 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1f050 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1f060 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1f070 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1f080 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1f090 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1f0a0 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1f0b0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1f0c0 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1f0d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1f0e0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1f0f0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1f100 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1f110 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1f120 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1f130 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1f140 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1f150 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1f160 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1f170 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1f180 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1f190 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1f1a0 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1f1b0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1f1c0 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1f1d0 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1f1e0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1f1f0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1f200 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1f210 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1f220 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1f230 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1f240 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1f250 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1f260 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1f270 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1f280 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1f290 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1f2a0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1f2b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1f2c0 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1f2d0 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1f2e0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1f2f0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1f300 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1f310 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1f320 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1f330 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1f340 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1f350 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1f360 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1f370 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1f380 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1f390 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1f3a0 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1f3b0 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1f3c0 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1f3d0 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1f3e0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1f3f0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1f400 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1f410 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1f420 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1f430 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1f440 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1f450 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1f460 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1f470 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1f480 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1f490 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1f4a0 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1f4b0 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1f4c0 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1f4d0 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1f4e0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1f4f0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1f500 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1f510 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1f520 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1f530 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1f540 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1f550 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1f560 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1f570 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1f580 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1f590 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1f5a0 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1f5b0 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1f5c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1f5d0 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1f5e0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1f5f0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1f600 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1f610 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1f620 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1f630 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1f640 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1f650 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1f660 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1f670 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1f680 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1f690 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1f6a0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1f6b0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1f6c0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1f6d0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f6e0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1f6f0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1f700 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1f710 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f720 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1f730 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f740 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1f750 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1f760 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1f770 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f780 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1f790 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1f7a0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1f7b0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1f7c0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1f7d0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1f7e0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1f7f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1f800 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1f810 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1f820 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1f830 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1f840 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1f850 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1f860 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1f870 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1f880 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1f890 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1f8a0 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1f8b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f8c0 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1f8d0 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1f8e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1f8f0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1f900 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1f910 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1f920 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1f930 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1f940 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1f950 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1f960 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1f970 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1f980 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1f990 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1f9b0 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1f9c0 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1f9d0 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1f9e0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1f9f0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1fa00 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1fa10 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1fa20 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1fa30 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1fa40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
1fa50 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1fa60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fa70 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
1fa80 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
1fa90 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
1faa0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1fab0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1fac0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
1fad0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
1fae0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1faf0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
1fb00 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
1fb10 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fb20 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1fb30 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1fb40 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
1fb50 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
1fb60 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
1fb70 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
1fb80 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
1fb90 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
1fba0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
1fbb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
1fbc0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
1fbd0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
1fbe0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1fbf0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1fc00 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
1fc10 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
1fc20 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
1fc30 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
1fc40 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
1fc50 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
1fc60 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
1fc70 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
1fc80 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
1fc90 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1fca0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1fcb0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1fcc0 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1fcd0 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1fce0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1fcf0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1fd00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd10 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1fd20 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1fd30 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1fd40 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1fd50 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1fd60 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1fd70 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1fd80 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1fd90 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1fda0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1fdb0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1fdc0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1fdd0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1fde0 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1fdf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1fe00 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1fe10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1fe20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1fe30 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1fe40 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1fe50 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1fe60 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1fe70 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1fe80 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1fe90 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1fea0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1feb0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1fec0 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1fed0 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1fee0 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1fef0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1ff00 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1ff10 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1ff20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1ff30 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1ff40 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1ff50 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1ff60 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1ff70 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1ff80 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1ff90 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1ffa0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1ffb0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1ffc0 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1ffd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ffe0 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1fff0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
20000 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
20010 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
20020 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
20030 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
20040 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
20050 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
20060 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
20070 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
20080 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
20090 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
200a0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
200b0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
200c0 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
200d0 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
200e0 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
200f0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
20100 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
20110 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
20120 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20130 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20140 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
20150 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
20160 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
20170 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
20180 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
20190 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
201a0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
201b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
201c0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
201d0 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
201e0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
201f0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20210 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
20220 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
20230 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
20240 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20260 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
20270 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
20280 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20290 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
202a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
202b0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
202c0 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
202d0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
202e0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
202f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20300 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
20310 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
20320 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20330 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20350 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
20360 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
20370 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20380 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
203a0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
203b0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
203c0 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
203d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
203e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
203f0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
20400 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
20410 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20420 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
20440 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
20450 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
20460 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
20470 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20480 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
20490 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
204a0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
204b0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
204c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
204d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
204e0 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
204f0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
20500 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
20510 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
20520 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20530 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
20540 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
20550 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20560 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20570 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
20580 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
20590 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
205a0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
205b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
205c0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
205d0 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
205e0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
205f0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20610 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
20620 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
20630 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
20640 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
20650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20660 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
20670 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
20680 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
20690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
206a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
206b0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
206c0 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
206d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
206e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
206f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20700 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
20710 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
20720 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
20730 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
20740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20750 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
20760 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
20770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20780 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
20790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
207a0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
207b0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
207c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
207d0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
207e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
207f0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
20800 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
20810 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
20820 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20840 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
20850 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
20860 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
20870 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
20880 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
20890 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
208a0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
208b0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
208c0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
208d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
208e0 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
208f0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
20900 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
20910 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20920 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
20930 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
20940 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
20950 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
20960 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20970 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
20980 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
20990 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
209a0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
209b0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
209c0 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
209d0 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
209e0 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
209f0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20a00 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20a10 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
20a20 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
20a30 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
20a40 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
20a50 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
20a60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
20a70 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
20a80 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20a90 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
20aa0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20ab0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
20ac0 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
20ad0 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
20ae0 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
20af0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
20b00 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
20b10 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
20b20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
20b30 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
20b40 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
20b50 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
20b60 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
20b70 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
20b80 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
20b90 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
20ba0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
20bb0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20bc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20bd0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
20be0 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
20bf0 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
20c00 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
20c10 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
20c20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
20c30 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
20c40 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
20c50 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
20c60 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
20c70 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
20c80 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
20c90 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
20ca0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
20cb0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
20cc0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
20cd0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
20ce0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
20cf0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
20d00 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
20d10 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
20d20 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
20d30 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
20d40 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
20d50 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
20d60 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
20d70 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
20d80 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
20d90 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
20da0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
20db0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
20dc0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
20dd0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
20de0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
20df0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
20e00 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
20e10 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
20e20 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
20e30 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
20e40 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
20e50 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
20e60 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
20e70 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
20e80 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
20e90 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
20ea0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
20eb0 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
20ec0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
20ed0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
20ee0 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
20ef0 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
20f00 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
20f10 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
20f20 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
20f30 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
20f40 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
20f50 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
20f60 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
20f70 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
20f80 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
20f90 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
20fa0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
20fb0 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
20fc0 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
20fd0 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
20fe0 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
20ff0 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
21000 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
21010 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
21020 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
21030 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
21040 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
21050 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
21060 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
21070 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
21080 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
21090 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
210a0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
210b0 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
210c0 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
210d0 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
210e0 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
210f0 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
21100 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
21110 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
21120 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
21130 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
21140 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
21150 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
21160 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
21170 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
21180 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
21190 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
211a0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
211b0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
211c0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72  DCALL sqlite3_tr
211d0 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
211e0 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
211f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
21200 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
21210 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
21220 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51 4c  MENTAL void *SQL
21230 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
21240 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
21250 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
21260 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
21270 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
21280 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
21290 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
212a0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
212b0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
212c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
212d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
212e0 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
212f0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
21300 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
21310 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
21320 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
21330 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
21340 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
21350 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
21360 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
21370 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
21380 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
21390 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
213a0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
213b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
213c0 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
213d0 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
213e0 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
213f0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
21400 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
21410 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
21420 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
21430 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
21440 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
21450 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
21460 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
21470 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
21480 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
21490 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
214a0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
214b0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
214c0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
214d0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
214e0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
214f0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
21500 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
21510 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
21520 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
21530 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
21540 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
21550 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
21560 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
21570 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
21580 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
21590 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
215a0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
215b0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
215c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
215d0 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
215e0 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
215f0 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
21600 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
21610 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21620 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
21630 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
21640 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
21650 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
21660 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
21670 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
21680 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
21690 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
216a0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
216b0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
216c0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
216d0 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
216e0 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
216f0 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
21700 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
21710 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
21720 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
21730 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
21740 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
21750 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
21760 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
21770 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
21780 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
21790 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
217a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
217b0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
217c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
217d0 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
217e0 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
217f0 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
21800 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
21810 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
21820 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
21830 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
21840 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
21850 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
21860 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
21870 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
21880 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
21890 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
218a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
218b0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
218c0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
218d0 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f  on.** CONSTRUCTO
218e0 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
218f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
21900 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20   open an SQLite 
21910 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73  database file as
21920 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
21930 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61  e .** filename a
21940 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69  rgument. ^The fi
21950 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
21960 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21970 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73  s UTF-8 for.** s
21980 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
21990 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
219a0 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31  2() and as UTF-1
219b0 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
219c0 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f  byte.** order fo
219d0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  r sqlite3_open16
219e0 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73  (). ^(A [databas
219f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
21a00 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a  ndle is usually.
21a10 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a  ** returned in *
21a20 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e  ppDb, even if an
21a30 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20   error occurs.  
21a40 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69  The only excepti
21a50 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66  on is that.** if
21a60 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
21a70 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65  e to allocate me
21a80 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
21a90 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
21aa0 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c  t,.** a NULL wil
21ab0 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74  l be written int
21ac0 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20  o *ppDb instead 
21ad0 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  of a pointer to 
21ae0 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a  the [sqlite3].**
21af0 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20   object.)^ ^(If 
21b00 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
21b10 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63  opened (and/or c
21b20 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66  reated) successf
21b30 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53  ully, then.** [S
21b40 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74  QLITE_OK] is ret
21b50 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73  urned.  Otherwis
21b60 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  e an [error code
21b70 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  ] is returned.)^
21b80 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   ^The.** [sqlite
21b90 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b  3_errmsg()] or [
21ba0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
21bb0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e  ()] routines can
21bc0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
21bd0 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68  in.** an English
21be0 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69   language descri
21bf0 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72  ption of the err
21c00 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  or following a f
21c10 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a  ailure of any.**
21c20 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
21c30 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e  open() routines.
21c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  .**.** ^The defa
21c50 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c  ult encoding wil
21c60 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64  l be UTF-8 for d
21c70 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64  atabases created
21c80 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65   using.** sqlite
21c90 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
21ca0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
21cb0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
21cc0 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61  oding for databa
21cd0 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75  ses.** created u
21ce0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  sing sqlite3_ope
21cf0 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54  n16() will be UT
21d00 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69  F-16 in the nati
21d10 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
21d20 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
21d30 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
21d40 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
21d50 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
21d60 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
21d70 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
21d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
21d90 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
21da0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
21db0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
21dc0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
21dd0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
21de0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
21df0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
21e00 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
21e10 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
21e20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
21e30 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
21e40 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
21e50 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
21e60 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
21e70 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
21e80 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
21e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
21ea0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
21eb0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
21ec0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
21ed0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
21ee0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21ef0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
21f00 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21f10 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
21f20 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
21f30 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
21f40 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
21f50 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
21f60 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
21f70 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
21f80 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
21f90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
21fa0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
21fb0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
21fc0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
21fd0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
21fe0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21ff0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
22000 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
22010 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
22020 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
22030 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
22040 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
22050 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
22060 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
22070 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
22080 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
22090 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
220a0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
220b0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
220c0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
220d0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
220e0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
220f0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
22100 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
22110 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
22120 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
22130 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
22140 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
22150 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
22160 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
22170 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22180 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
22190 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
221a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
221b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
221c0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
221d0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
221e0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
221f0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
22200 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
22210 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
22220 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
22230 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
22240 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
22250 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
22260 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
22270 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
22280 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
22290 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
222a0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
222b0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
222c0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
222d0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
222e0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
222f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
22300 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
22310 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
22320 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
22330 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
22340 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
22350 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
22360 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
22370 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22380 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
22390 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
223a0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
223b0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
223c0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
223d0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
223e0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
223f0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
22400 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
22410 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
22420 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
22430 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
22440 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
22450 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
22460 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
22470 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
22480 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
22490 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
224a0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
224b0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
224c0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
224d0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
224e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
224f0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
22500 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
22510 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
22520 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
22530 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
22540 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
22550 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
22560 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
22570 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
22580 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
22590 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
225a0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
225b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
225c0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
225d0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
225e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
225f0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
22600 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
22610 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
22620 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
22630 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
22640 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
22650 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
22660 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
22670 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
22680 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
22690 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
226a0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
226b0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
226c0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
226d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
226e0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
226f0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
22700 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
22710 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
22720 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
22730 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
22740 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
22750 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
22760 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
22770 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
22780 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
22790 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
227a0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
227b0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
227c0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
227d0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
227e0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
227f0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22800 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
22810 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
22820 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
22830 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
22840 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
22850 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
22860 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
22870 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
22880 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
22890 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
228a0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
228b0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
228c0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
228d0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
228e0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
228f0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
22900 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
22910 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
22920 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
22930 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
22940 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
22950 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
22960 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22970 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
22980 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
22990 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
229a0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
229b0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
229c0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
229d0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
229e0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
229f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
22a00 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
22a10 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
22a20 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
22a30 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
22a40 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
22a50 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
22a60 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
22a70 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
22a80 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
22a90 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
22aa0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
22ab0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
22ac0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22ad0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
22ae0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
22af0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22b00 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
22b10 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
22b20 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
22b30 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
22b40 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
22b50 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
22b60 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
22b70 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
22b80 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
22b90 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
22ba0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
22bb0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
22bc0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
22bd0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
22be0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
22bf0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
22c00 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
22c10 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
22c20 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
22c30 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
22c40 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
22c50 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
22c60 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
22c70 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
22c80 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
22c90 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
22ca0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
22cb0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
22cc0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
22cd0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
22ce0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
22cf0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
22d00 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
22d10 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
22d20 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
22d30 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
22d40 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
22d50 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
22d60 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
22d70 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
22d80 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
22d90 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
22da0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
22db0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
22dc0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
22dd0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
22de0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
22df0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
22e00 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
22e10 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
22e20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
22e30 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
22e40 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
22e50 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
22e60 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
22e70 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
22e80 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
22e90 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
22ea0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
22eb0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
22ec0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
22ed0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
22ee0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
22ef0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
22f00 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
22f10 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
22f20 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
22f30 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
22f40 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
22f50 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
22f60 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22f70 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
22f80 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f  . .** ^(On windo
22f90 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
22fa0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
22fb0 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
22fc0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
22fd0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
22fe0 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  C:").)^.**.** [[
22ff0 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
23000 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
23010 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
23020 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
23030 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
23040 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
23050 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
23060 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
23070 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
23080 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
23090 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
230a0 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73  * SQLite and its
230b0 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73   built-in [VFSes
230c0 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a  ] interpret the.
230d0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65  ** following que
230e0 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a  ry parameters:.*
230f0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c  *.** <ul>.**   <
23100 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20  li> <b>vfs</b>: 
23110 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d  ^The "vfs" param
23120 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64  eter may be used
23130 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
23140 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61  name of.**     a
23150 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74   VFS object that
23160 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70   provides the op
23170 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
23180 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68  nterface that sh
23190 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75  ould.**     be u
231a0 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68  sed to access th
231b0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
231c0 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69  on disk. ^If thi
231d0 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  s option is set 
231e0 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70  to.**     an emp
231f0 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65  ty string the de
23200 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74  fault VFS object
23210 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69   is used. ^Speci
23220 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
23230 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61  .**     VFS is a
23240 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c  n error. ^If sql
23250 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23260 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76  s used and the v
23270 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  fs option is.** 
23280 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65      present, the
23290 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66  n the VFS specif
232a0 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f  ied by the optio
232b0 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e  n takes preceden
232c0 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74  ce over.**     t
232d0 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
232e0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  as the fourth pa
232f0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
23300 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
23310 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f  .**   <li> <b>mo
23320 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f  de</b>: ^(The mo
23330 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  de parameter may
23340 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
23350 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a  r "ro", "rw",.**
23360 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22       "rwc", or "
23370 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74  memory". Attempt
23380 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f  ing to set it to
23390 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65   any other value
233a0 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72   is.**     an er
233b0 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e  ror)^. .**     ^
233c0 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69  If "ro" is speci
233d0 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64  fied, then the d
233e0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
233f0 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  d for read-only 
23400 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20  .**     access, 
23410 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b  just as if the [
23420 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23430 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62  ONLY] flag had b
23440 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a  een set in the .
23450 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67  **     third arg
23460 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
23470 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20  _open_v2(). ^If 
23480 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
23490 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
234a0 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
234b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
234c0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
234d0 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
234e0 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
234f0 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
23500 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
23510 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
23520 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
23530 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
23540 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
23550 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
23560 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
23570 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
23580 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
23590 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
235a0 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64  TE.  ^If the mod
235b0 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  e option is.**  
235c0 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72     set to "memor
235d0 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b  y" then a pure [
235e0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
235f0 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72  se] that never r
23600 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77  eads.**     or w
23610 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20  rites from disk 
23620 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20  is used. ^It is 
23630 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63  an error to spec
23640 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a  ify a value for.
23650 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20  **     the mode 
23660 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
23670 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69  s less restricti
23680 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65  ve than that spe
23690 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
236a0 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65   the flags passe
236b0 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70  d in the third p
236c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
236d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
236e0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63  *.**   <li> <b>c
236f0 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63  ache</b>: ^The c
23700 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d  ache parameter m
23710 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
23720 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a  her "shared" or.
23730 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22  **     "private"
23740 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f  . ^Setting it to
23750 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75   "shared" is equ
23760 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
23770 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51  ng the.**     SQ
23780 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23790 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65  CACHE bit in the
237a0 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
237b0 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20  passed to.**    
237c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
237d0 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65  (). ^Setting the
237e0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
237f0 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73   to "private" is
23800 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c   .**     equival
23810 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74  ent to setting t
23820 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  he SQLITE_OPEN_P
23830 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e  RIVATECACHE bit.
23840 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69  .**     ^If sqli
23850 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
23860 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63   used and the "c
23870 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20  ache" parameter 
23880 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a  is present in.**
23890 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e       a URI filen
238a0 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f  ame, its value o
238b0 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68  verrides any beh
238c0 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20  avior requested 
238d0 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20  by setting.**   
238e0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52    SQLITE_OPEN_PR
238f0 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51  IVATECACHE or SQ
23900 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23910 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a  CACHE flag..**.*
23920 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c  *  <li> <b>psow<
23930 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70  /b>: ^The psow p
23940 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74  arameter indicat
23950 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  es whether or no
23960 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f  t the.**     [po
23970 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74  wersafe overwrit
23980 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73  e] property does
23990 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70   or does not app
239a0 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20  ly to the.**    
239b0 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f   storage media o
239c0 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61  n which the data
239d0 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65  base file reside
239e0 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  s..**.**  <li> <
239f0 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54  b>nolock</b>: ^T
23a00 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65  he nolock parame
23a10 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  ter is a boolean
23a20 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23a30 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66  .**     which if
23a40 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69   set disables fi
23a50 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f  le locking in ro
23a60 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d  llback journal m
23a70 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20  odes.  This.**  
23a80 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72     is useful for
23a90 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74   accessing a dat
23aa0 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73  abase on a files
23ab0 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20  ystem that does 
23ac0 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f  not.**     suppo
23ad0 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75  rt locking.  Cau
23ae0 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20  tion:  Database 
23af0 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74  corruption might
23b00 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a   result if two.*
23b10 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72  *     or more pr
23b20 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f  ocesses write to
23b30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
23b40 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f  se and any one o
23b50 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70  f those.**     p
23b60 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f  rocesses uses no
23b70 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c  lock=1..**.**  <
23b80 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65  li> <b>immutable
23b90 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74  </b>: ^The immut
23ba0 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69  able parameter i
23bb0 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
23bc0 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74  y.**     paramet
23bd0 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  er that indicate
23be0 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62  s that the datab
23bf0 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72  ase file is stor
23c00 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61  ed on.**     rea
23c10 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e  d-only media.  ^
23c20 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69  When immutable i
23c30 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73  s set, SQLite as
23c40 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
23c50 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66  *     database f
23c60 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  ile cannot be ch
23c70 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61  anged, even by a
23c80 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69   process with hi
23c90 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76  gher.**     priv
23ca0 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68  ilege, and so th
23cb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23cc0 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61  ened read-only a
23cd0 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a  nd all locking.*
23ce0 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65  *     and change
23cf0 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69   detection is di
23d00 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e  sabled.  Caution
23d10 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d  : Setting the im
23d20 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70  mutable.**     p
23d30 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74  roperty on a dat
23d40 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20  abase file that 
23d50 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61  does in fact cha
23d60 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a  nge can result.*
23d70 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65  *     in incorre
23d80 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  ct query results
23d90 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
23da0 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e  CORRUPT] errors.
23db0 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f  .**     See also
23dc0 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  : [SQLITE_IOCAP_
23dd0 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20  IMMUTABLE]..**  
23de0 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a       .** </ul>.*
23df0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
23e00 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
23e10 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
23e20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
23e30 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
23e40 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
23e50 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23e60 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
23e70 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
23e80 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
23e90 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
23ea0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
23eb0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
23ec0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
23ed0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
23ee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
23ef0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
23f00 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
23f10 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
23f20 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
23f30 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
23f40 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
23f50 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
23f60 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
23f70 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
23f80 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
23f90 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
23fa0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23fb0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
23fc0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
23fd0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
23fe0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
23ff0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
24000 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
24010 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
24020 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24030 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
24040 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
24050 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
24060 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
24070 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
24080 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
24090 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
240a0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
240b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
240c0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
240d0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
240e0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
240f0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
24100 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
24110 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
24120 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
24130 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
24140 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
24150 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
24160 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
24170 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
24180 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
24190 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
241a0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
241b0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
241c0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
241d0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
241e0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
241f0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
24200 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
24210 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
24220 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
24230 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
24240 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
24250 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
24260 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
24270 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
24280 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
24290 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
242a0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
242b0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
242c0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
242d0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
242e0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
242f0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
24300 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
24310 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
24320 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
24330 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
24340 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
24350 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
24360 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
24370 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
24380 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
24390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
243a0 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65  vfs=unix-dotfile
243b0 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
243c0 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
243d0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
243e0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
243f0 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66  l VFS "unix-dotf
24400 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20  ile".**         
24410 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66   that uses dot-f
24420 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  iles in place of
24430 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20   posix advisory 
24440 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e  locking..** <tr>
24450 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
24460 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
24470 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24480 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
24490 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
244a0 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
244b0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
244c0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
244d0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
244e0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
244f0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
24500 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
24510 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
24520 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
24530 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
24540 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
24550 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
24560 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
24570 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
24580 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
24590 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
245a0 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
245b0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
245c0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
245d0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
245e0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
245f0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
24600 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
24610 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
24620 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
24630 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
24640 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
24650 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
24660 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
24670 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
24680 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
24690 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
246a0 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
246b0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
246c0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
246d0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
246e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
246f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
24700 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
24710 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
24720 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
24730 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
24740 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
24750 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
24760 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24770 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
24780 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
24790 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
247a0 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
247b0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
247c0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
247d0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
247e0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
247f0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
24800 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
24810 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
24820 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
24830 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
24840 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
24850 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
24860 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
24870 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
24880 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
24890 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
248a0 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
248b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
248c0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
248d0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
248e0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
248f0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
24900 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
24910 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
24920 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
24930 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
24940 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
24950 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
24960 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
24970 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
24980 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
24990 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
249a0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
249b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
249c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
249d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
249e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
249f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
24a00 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  LL sqlite3_open1
24a10 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
24a20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
24a30 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
24a40 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
24a50 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24a60 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24a70 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
24a80 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
24a90 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
24aa0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
24ab0 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
24ac0 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
24ad0 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
24ae0 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
24af0 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
24b00 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
24b10 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
24b20 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
24b30 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
24b40 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
24b50 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
24b60 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
24b70 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
24b80 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
24b90 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
24ba0 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
24bb0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
24bc0 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
24bd0 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
24be0 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
24bf0 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
24c00 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
24c10 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
24c20 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
24c30 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
24c40 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
24c50 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
24c60 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
24c70 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
24c80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24c90 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
24ca0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
24cb0 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
24cc0 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
24cd0 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
24ce0 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
24cf0 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
24d00 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
24d10 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
24d20 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
24d30 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
24d40 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
24d50 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
24d60 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
24d70 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
24d80 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
24d90 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
24da0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24db0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24dc0 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
24dd0 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
24de0 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
24df0 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
24e00 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
24e10 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
24e20 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24e30 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
24e40 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
24e50 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
24e60 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
24e70 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
24e80 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
24e90 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
24ea0 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
24eb0 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
24ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
24ed0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
24ee0 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
24ef0 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
24f00 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
24f10 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
24f20 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
24f30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
24f40 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
24f50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
24f60 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24f70 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
24f80 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
24f90 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
24fa0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
24fb0 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
24fc0 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
24fd0 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
24fe0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
24ff0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
25000 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
25010 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
25020 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25030 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
25040 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
25050 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
25060 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25070 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
25080 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
25090 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
250a0 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
250b0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
250c0 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
250d0 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
250e0 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
250f0 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
25100 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
25110 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
25120 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
25130 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
25140 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
25150 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
25160 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
25170 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
25180 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
25190 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
251a0 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
251b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
251c0 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
251d0 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
251e0 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
251f0 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
25200 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
25210 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
25220 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
25230 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
25240 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
25250 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
25260 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
25270 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
25280 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
25290 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
252a0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
252b0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
252c0 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
252d0 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
252e0 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
252f0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25300 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
25310 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
25320 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
25330 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
25340 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
25350 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
25360 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
25370 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
25380 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
25390 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
253a0 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  st char *SQLITE_
253b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
253c0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
253d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
253e0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
253f0 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
25400 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
25410 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
25420 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
25430 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
25440 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
25450 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
25460 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
25470 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
25480 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
25490 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
254a0 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
254b0 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
254c0 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
254d0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
254e0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
254f0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25500 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te3.**.** ^If th
25510 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 71  e most recent sq
25520 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
25530 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
25540 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63   .** [database c
25550 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61 69  onnection] D fai
25560 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73 71  led, then the sq
25570 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44 29  lite3_errcode(D)
25580 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
25590 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
255a0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
255b0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  or [extended res
255c0 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
255d0 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e 0a  at.** API call..
255e0 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20 72  ** If the most r
255f0 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 77  ecent API call w
25600 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a 2a  as successful,.*
25610 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72  * then the retur
25620 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
25630 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
25640 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
25650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
25660 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
25670 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
25680 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
25690 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
256a0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
256b0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
256c0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
256d0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
256e0 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
256f0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
25700 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
25710 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
25720 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
25730 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
25740 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
25750 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
25760 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
25770 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
25780 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
25790 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
257a0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
257b0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
257c0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
257d0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
257e0 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
257f0 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
25800 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
25810 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
25820 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
25830 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
25840 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
25850 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
25860 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
25870 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
25880 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
25890 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
258a0 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69  lite3_errstr() i
258b0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
258c0 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e   the English-lan
258d0 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68  guage text.** th
258e0 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
258f0 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20   [result code], 
25900 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d  as UTF-8..** ^(M
25910 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
25920 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
25930 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65  string is manage
25940 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  d internally.** 
25950 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20  and must not be 
25960 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70  freed by the app
25970 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a  lication)^..**.*
25980 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61  * When the seria
25990 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
259a0 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65   mode] is in use
259b0 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68  , it might be th
259c0 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61  e.** case that a
259d0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63   second error oc
259e0 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61  curs on a separa
259f0 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74  te thread in bet
25a00 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65  ween.** the time
25a10 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72   of the first er
25a20 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  ror and the call
25a30 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
25a40 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  aces..** When th
25a50 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  at happens, the 
25a60 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c  second error wil
25a70 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69  l be reported si
25a80 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74  nce these.** int
25a90 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72  erfaces always r
25aa0 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72  eport the most r
25ab0 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54  ecent result.  T
25ac0 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c  o avoid.** this,
25ad0 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e   each thread can
25ae0 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76   obtain exclusiv
25af0 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61  e use of the [da
25b00 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25b10 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b  n] D.** by invok
25b20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
25b30 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74  ex_enter]([sqlit
25b40 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
25b50 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e   before beginnin
25b60 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e  g.** to use D an
25b70 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  d invoking [sqli
25b80 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d  te3_mutex_leave]
25b90 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
25ba0 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a  ex](D)) after.**
25bb0 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68   all calls to th
25bc0 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73  e interfaces lis
25bd0 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d  ted here are com
25be0 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  pleted..**.** If
25bf0 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61   an interface fa
25c00 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f  ils with SQLITE_
25c10 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61  MISUSE, that mea
25c20 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ns the interface
25c30 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20  .** was invoked 
25c40 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74  incorrectly by t
25c50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
25c60 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74   In that case, t
25c70 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65  he.** error code
25c80 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79   and message may
25c90 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73   or may not be s
25ca0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
25cb0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
25cc0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
25cd0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
25ce0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25cf0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
25d00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25d10 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
25d20 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
25d30 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
25d40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d50 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
25d60 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
25d70 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
25d80 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
25d90 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
25da0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
25db0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25dc0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
25dd0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
25de0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25df0 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53  3REF: Prepared S
25e00 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
25e10 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
25e20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25e30 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
25e40 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
25e50 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
25e60 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
25e70 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
25e80 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a   statement that.
25e90 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70  ** has been comp
25ea0 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79  iled into binary
25eb0 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61   form and is rea
25ec0 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74  dy to be evaluat
25ed0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20  ed..**.** Think 
25ee0 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74  of each SQL stat
25ef0 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72  ement as a separ
25f00 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f  ate computer pro
25f10 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72  gram.  The.** or
25f20 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20  iginal SQL text 
25f30 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
25f40 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74   A prepared stat
25f50 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a  ement object .**
25f60 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64   is the compiled
25f70 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41   object code.  A
25f80 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63  ll SQL must be c
25f90 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a  onverted into a.
25fa0 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
25fb0 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20  ement before it 
25fc0 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a  can be run..**.*
25fd0 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65  * The life-cycle
25fe0 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73   of a prepared s
25ff0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
26000 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b  usually goes lik
26010 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
26020 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
26030 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  e the prepared s
26040 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
26050 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
26060 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a  repare_v2()]..**
26070 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65   <li> Bind value
26080 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73  s to [parameters
26090 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
260a0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
260b0 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
260c0 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
260d0 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
260e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
260f0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
26100 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
26110 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
26120 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
26130 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
26140 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a   then go back.**
26150 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e        to step 2.
26160 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f    Do this zero o
26170 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a  r more times..**
26180 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68   <li> Destroy th
26190 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
261a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
261b0 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f  ()]..** </ol>.*/
261c0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
261d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c  sqlite3_stmt sql
261e0 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a  ite3_stmt;../*.*
261f0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
26200 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d  time Limits.** M
26210 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
26220 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
26230 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
26240 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
26250 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
26260 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
26270 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
26280 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
26290 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
262a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
262b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
262c0 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
262d0 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
262e0 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
262f0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
26300 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
26310 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
26320 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
26330 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
26340 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26350 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
26360 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
26370 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
26380 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
26390 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
263a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
263b0 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
263c0 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
263d0 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
263e0 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
263f0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
26400 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
26410 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
26420 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
26430 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
26440 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
26450 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
26460 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
26470 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
26480 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
26490 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
264a0 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
264b0 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
264c0 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
264d0 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
264e0 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
264f0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
26500 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
26510 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
26520 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
26530 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
26540 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
26550 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
26560 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
26570 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
26580 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
26590 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
265a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
265b0 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
265c0 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
265d0 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
265e0 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
265f0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
26600 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
26610 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
26620 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
26630 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
26640 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
26650 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
26660 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
26670 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
26680 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
26690 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
266a0 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
266b0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
266c0 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
266d0 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
266e0 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
266f0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
26700 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
26710 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
26720 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
26730 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
26740 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
26750 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
26760 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
26770 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
26780 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
26790 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
267a0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
267b0 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
267c0 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
267d0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
267e0 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
267f0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
26800 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
26810 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
26820 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
26830 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
26840 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
26850 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
26860 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
26870 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
26880 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
26890 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
268a0 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
268b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
268c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
268d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
268e0 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
268f0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
26900 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
26910 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
26920 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
26930 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
26940 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
26950 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
26960 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
26970 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
26980 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
26990 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
269a0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
269b0 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49  eleases..*/.SQLI
269c0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
269d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
269e0 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
269f0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
26a00 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
26a10 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
26a20 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
26a30 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26a40 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
26a50 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
26a60 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
26a70 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
26a80 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
26a90 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
26aa0 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
26ab0 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
26ac0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
26ad0 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
26ae0 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
26af0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
26b00 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
26b10 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
26b20 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
26b30 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
26b40 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
26b50 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
26b60 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
26b70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
26b80 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
26b90 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
26ba0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
26bb0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
26bc0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
26bd0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
26be0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
26bf0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26c00 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26c10 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
26c20 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
26c30 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
26c40 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
26c50 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
26c60 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
26c70 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
26c80 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c90 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
26ca0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
26cb0 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
26cc0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26cd0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
26ce0 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
26cf0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
26d00 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
26d10 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
26d20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26d30 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
26d40 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
26d50 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
26d60 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
26d70 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26d80 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26d90 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
26da0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
26db0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
26dc0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
26dd0 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
26de0 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
26df0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
26e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26e10 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
26e20 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
26e30 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26e40 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
26e50 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26e60 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
26e70 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
26e80 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
26e90 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26ea0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
26eb0 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
26ec0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
26ed0 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
26ee0 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26ef0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
26f00 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
26f10 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
26f20 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
26f30 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
26f40 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
26f50 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
26f60 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
26f70 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
26f80 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
26f90 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
26fa0 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
26fb0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
26fc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
26fd0 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
26fe0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
26ff0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
27000 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
27010 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
27020 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
27030 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
27040 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27050 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27060 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27070 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27080 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27090 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
270a0 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
270b0 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
270c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
270d0 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
270e0 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
270f0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27100 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
27110 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
27120 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
27130 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
27140 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27150 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27160 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27170 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27180 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27190 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
271a0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
271b0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
271c0 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
271d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
271e0 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
271f0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
27200 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
27210 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
27220 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
27230 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
27240 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27250 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27260 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27270 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27280 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27290 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ers.</dd>)^.**.*
272a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
272b0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d  _WORKER_THREADS]
272c0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
272d0 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45  IMIT_WORKER_THRE
272e0 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ADS</dt>.** <dd>
272f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27300 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20  er of auxiliary 
27310 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20 74  worker threads t
27320 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20  hat a single.** 
27330 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27340 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c  ent] may start.<
27350 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27370 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27380 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27390 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
273a0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
273b0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
273c0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
273d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
273e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
273f0 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27400 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27410 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
27420 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
27430 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27440 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27450 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27470 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27480 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27490 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
274a0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
274b0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
274c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
274d0 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
274e0 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
274f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27500 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
27510 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
27520 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27530 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27540 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
27550 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27560 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
27570 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64             10.#d
27580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27590 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
275a0 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a  S           11..
275b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
275c0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
275d0 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
275e0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
275f0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
27600 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
27610 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  te3.** CONSTRUCT
27620 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
27630 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
27640 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
27650 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
27660 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
27670 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
27680 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
27690 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
276a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
276b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
276c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
276d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
276e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
276f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
27700 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
27710 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
27720 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
27730 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
27740 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
27750 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27760 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
27770 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
27780 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
27790 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
277a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
277b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
277c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
277d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
277e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
277f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
27800 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
27810 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
27820 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
27830 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27840 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
27850 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27860 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
27870 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
27880 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
27890 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
278a0 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
278b0 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
278c0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
278d0 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
278e0 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69  positive, then i
278f0 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  t is the.** numb
27900 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61 64  er of bytes read
27910 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66   from zSql.  ^If
27920 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20   nByte is zero, 
27930 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64  then no prepared
27940 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73  .** statement is
27950 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49   generated..** I
27960 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
27970 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ws that the supp
27980 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
27990 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
279a0 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20  hen.** there is 
279b0 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61  a small performa
279c0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
279d0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
279e0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
279f0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
27a00 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27a10 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
27a20 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
27a30 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
27a40 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nator..**.** ^If
27a50 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e   pzTail is not N
27a60 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c  ULL then *pzTail
27a70 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e   is made to poin
27a80 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 62  t to the first b
27a90 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20  yte.** past the 
27aa0 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73 74  end of the first
27ab0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
27ac0 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72  n zSql.  These r
27ad0 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20  outines only.** 
27ae0 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73  compile the firs
27af0 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  t statement in z
27b00 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20  Sql, so *pzTail 
27b10 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
27b20 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61   to.** what rema
27b30 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a  ins uncompiled..
27b40 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69  **.** ^*ppStmt i
27b50 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20  s left pointing 
27b60 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70  to a compiled [p
27b70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27b80 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a  t] that can be.*
27b90 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e 67  * executed using
27ba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27bb0 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69 73  ].  ^If there is
27bc0 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74   an error, *ppSt
27bd0 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20  mt is set.** to 
27be0 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69  NULL.  ^If the i
27bf0 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69  nput text contai
27c00 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68  ns no SQL (if th
27c10 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d  e input is an em
27c20 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72  pty.** string or
27c30 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e   a comment) then
27c40 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 20   *ppStmt is set 
27c50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20  to NULL..** The 
27c60 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72  calling procedur
27c70 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  e is responsible
27c80 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68   for deleting th
27c90 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51  e compiled.** SQ
27ca0 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  L statement usin
27cb0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
27cc0 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74 20  ize()] after it 
27cd0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
27ce0 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20  h it..** ppStmt 
27cf0 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e  may not be NULL.
27d00 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65  .**.** ^On succe
27d10 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ss, the sqlite3_
27d20 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79  prepare() family
27d30 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74   of routines ret
27d40 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b  urn [SQLITE_OK];
27d50 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
27d60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
27d70 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
27d80 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
27d90 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71  pare_v2() and sq
27da0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
27db0 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  v2() interfaces 
27dc0 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64  are.** recommend
27dd0 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70  ed for all new p
27de0 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f  rograms. The two
27df0 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65   older interface
27e00 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a  s are retained.*
27e10 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  * for backwards 
27e20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62  compatibility, b
27e30 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73 20  ut their use is 
27e40 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20  discouraged..** 
27e50 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74  ^In the "v2" int
27e60 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72 65  erfaces, the pre
27e70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
27e80 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75 72  ** that is retur
27e90 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ned (the [sqlite
27ea0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20  3_stmt] object) 
27eb0 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20  contains a copy 
27ec0 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  of the.** origin
27ed0 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69  al SQL text. Thi
27ee0 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73 71  s causes the [sq
27ef0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e  lite3_step()] in
27f00 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65  terface to.** be
27f10 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79  have differently
27f20 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a   in three ways:.
27f30 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
27f40 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  i>.** ^If the da
27f50 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68  tabase schema ch
27f60 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f  anges, instead o
27f70 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c  f returning [SQL
27f80 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69  ITE_SCHEMA] as i
27f90 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64  t.** always used
27fa0 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33   to do, [sqlite3
27fb0 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75  _step()] will au
27fc0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
27fd0 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a  mpile the SQL.**
27fe0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
27ff0 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61  ry to run it aga
28000 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b  in. As many as [
28010 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d  SQLITE_MAX_SCHEM
28020 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72  A_RETRY].** retr
28030 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62  ies will occur b
28040 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74  efore sqlite3_st
28050 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61 6e  ep() gives up an
28060 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  d returns an err
28070 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  or..** </li>.**.
28080 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e  ** <li>.** ^When
28090 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
280a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
280b0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f  )] will return o
280c0 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c  ne of the detail
280d0 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64  ed.** [error cod
280e0 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64  es] or [extended
280f0 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20   error codes].  
28100 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68 61  ^The legacy beha
28110 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a  vior was that.**
28120 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28130 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74  ] would only ret
28140 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53  urn a generic [S
28150 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73  QLITE_ERROR] res
28160 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20  ult code.** and 
28170 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
28180 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61  would have to ma
28190 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ke a second call
281a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
281b0 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65  et()].** in orde
281c0 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e  r to find the un
281d0 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f  derlying cause o
281e0 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57  f the problem. W
281f0 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72 65  ith the "v2" pre
28200 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  pare.** interfac
28210 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69  es, the underlyi
28220 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68  ng reason for th
28230 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  e error is retur
28240 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  ned immediately.
28250 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
28260 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  <li>.** ^If the 
28270 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 62  specific value b
28280 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74  ound to [paramet
28290 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65  er | host parame
282a0 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20  ter] in the .** 
282b0 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67  WHERE clause mig
282c0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
282d0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
282e0 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74   plan for a stat
282f0 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74  ement,.** then t
28300 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c  he statement wil
28310 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
28320 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61  ly recompiled, a
28330 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20 62  s if there had b
28340 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61  een .** a schema
28350 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20   change, on the 
28360 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f  first  [sqlite3_
28370 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c  step()] call fol
28380 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67  lowing any chang
28390 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  e.** to the [sql
283a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c  ite3_bind_text |
283b0 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68   bindings] of th
283c0 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20  at [parameter]. 
283d0 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69  .** ^The specifi
283e0 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45  c value of WHERE
283f0 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74  -clause [paramet
28400 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  er] might influe
28410 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69  nce the .** choi
28420 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28430 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
28440 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61  r is the left-ha
28450 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49  nd side of a [LI
28460 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d  KE].** or [GLOB]
28470 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20   operator or if 
28480 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28490 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20   compared to an 
284a0 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a  indexed column.*
284b0 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54  * and the [SQLIT
284c0 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20  E_ENABLE_STAT3] 
284d0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
284e0 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
284f0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c  ** </li>.** </ol
28500 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
28510 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
28520 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  LL sqlite3_prepa
28530 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
28540 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
28550 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
28560 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
28570 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
28580 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
28590 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
285a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
285b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
285c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
285d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
285e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
285f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28600 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28610 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28620 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28630 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28640 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28650 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28660 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28670 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28680 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28690 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
286a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
286b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
286c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
286d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
286e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
286f0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
28700 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28710 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28720 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28730 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28740 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28750 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28760 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28770 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28780 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
28790 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
287a0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
287b0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
287c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
287d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
287e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
287f0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
28800 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28810 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28820 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28830 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28840 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28850 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28860 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28870 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28880 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28890 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
288a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
288b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
288c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
288d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
288e0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
288f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28900 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28910 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28920 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
28930 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
28940 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28950 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  6_v2(.  sqlite3 
28960 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
28970 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
28980 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
28990 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  id *zSql,       
289a0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
289b0 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64  , UTF-16 encoded
289c0 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
289d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
289e0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
289f0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
28a00 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
28a10 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
28a20 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
28a30 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28a40 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c  st void **pzTail
28a50 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
28a60 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
28a70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
28a80 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
28a90 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67  3REF: Retrieving
28aa0 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a   Statement SQL.*
28ab0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
28ac0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
28ad0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
28ae0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
28af0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
28b00 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
28b10 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
28b20 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
28b30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28b40 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
28b50 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
28b60 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
28b70 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
28b80 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
28b90 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
28ba0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
28bb0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
28bc0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
28bd0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
28be0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28bf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28c00 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
28c10 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
28c20 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
28c30 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
28c40 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
28c50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
28c60 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
28c70 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
28c80 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
28c90 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
28ca0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
28cb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
28cc0 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
28cd0 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
28ce0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
28cf0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
28d00 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
28d10 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
28d20 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28d30 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
28d40 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
28d50 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
28d60 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
28d70 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
28d80 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
28d90 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
28da0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
28db0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
28dc0 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
28dd0 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
28de0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
28df0 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
28e00 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
28e10 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
28e20 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
28e30 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
28e40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
28e50 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
28e60 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
28e70 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
28e80 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
28e90 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
28ea0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
28eb0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
28ec0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
28ed0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
28ee0 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
28ef0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
28f00 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
28f10 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
28f20 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
28f30 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
28f40 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
28f50 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
28f60 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
28f70 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
28f80 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
28f90 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
28fa0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
28fb0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
28fc0 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
28fd0 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
28fe0 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
28ff0 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
29000 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
29010 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
29020 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
29030 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
29040 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
29050 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
29060 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
29070 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
29080 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
29090 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
290a0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
290b0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
290c0 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
290d0 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
290e0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
290f0 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
29100 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
29110 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
29120 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
29130 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
29140 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
29150 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
29160 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
29170 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29180 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
29190 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
291a0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
291b0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
291c0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
291d0 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
291e0 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
291f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
29200 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29210 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
29220 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29230 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
29240 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
29250 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
29260 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
29270 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
29280 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
29290 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
292a0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
292b0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
292c0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
292d0 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
292e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
292f0 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
29300 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
29310 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
29320 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
29330 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
29340 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
29350 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
29360 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
29370 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
29380 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
29390 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
293a0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
293b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
293c0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
293d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
293e0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
293f0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
29400 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
29410 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
29420 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
29430 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
29440 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
29450 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
29460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
29470 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
29480 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
29490 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
294a0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
294b0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
294c0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
294d0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
294e0 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
294f0 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
29500 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
29510 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
29520 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
29530 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
29540 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29550 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
29560 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29570 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  sy(sqlite3_stmt*
29580 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
29590 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20  EF: Dynamically 
295a0 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65  Typed Value Obje
295b0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
295c0 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  {protected sqlit
295d0 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f  e3_value} {unpro
295e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
295f0 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  alue}.**.** SQLi
29600 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69  te uses the sqli
29610 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29620 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c   to represent al
29630 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  l values.** that
29640 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69   can be stored i
29650 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
29660 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20  le. SQLite uses 
29670 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a  dynamic typing.*
29680 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73  * for the values
29690 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61   it stores.  ^Va
296a0 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73  lues stored in s
296b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
296c0 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69  ects.** can be i
296d0 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e  ntegers, floatin
296e0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20  g point values, 
296f0 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20  strings, BLOBs, 
29700 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41  or NULL..**.** A
29710 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
29720 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69  object may be ei
29730 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22  ther "protected"
29740 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64   or "unprotected
29750 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72  "..** Some inter
29760 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20  faces require a 
29770 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29780 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20  3_value.  Other 
29790 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69  interfaces.** wi
297a0 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72  ll accept either
297b0 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20   a protected or 
297c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
297d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
297e0 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65   Every interface
297f0 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71   that accepts sq
29800 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75  lite3_value argu
29810 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a  ments specifies.
29820 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** whether or no
29830 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20  t it requires a 
29840 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29850 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a  3_value.  The.**
29860 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
29870 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  dup()] interface
29880 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
29890 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20  construct a new 
298a0 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71  .** protected sq
298b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d  lite3_value from
298c0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
298d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
298e0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
298f0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
29900 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
29910 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
29920 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
29930 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
29940 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
29950 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
29960 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29970 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
29980 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
29990 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
299a0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
299b0 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
299c0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
299d0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
299e0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
299f0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
29a00 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
29a10 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
29a20 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
29a30 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
29a40 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
29a50 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
29a60 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
29a70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
29a80 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
29a90 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
29aa0 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
29ab0 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
29ac0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
29ad0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
29ae0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29af0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29b00 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
29b10 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
29b20 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
29b30 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
29b40 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
29b50 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
29b60 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
29b70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
29b80 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
29b90 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
29ba0 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
29bb0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
29bc0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
29bd0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
29be0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
29bf0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
29c00 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29c10 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
29c20 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
29c30 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
29c40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
29c50 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
29c60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
29c70 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
29c80 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
29c90 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29ca0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
29cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
29cc0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
29cd0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
29ce0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29cf0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
29d00 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
29d10 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
29d20 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
29d30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
29d40 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
29d50 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
29d60 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
29d70 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
29d80 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
29d90 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
29da0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29db0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
29dc0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
29dd0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
29de0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
29df0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
29e00 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
29e10 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
29e20 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
29e30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
29e40 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
29e50 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
29e60 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
29e70 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
29e80 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
29e90 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
29ea0 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
29eb0 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
29ec0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
29ed0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
29ee0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
29ef0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
29f00 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
29f10 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
29f20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
29f30 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
29f40 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
29f50 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
29f60 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
29f70 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
29f80 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
29f90 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
29fa0 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
29fb0 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
29fc0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
29fd0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
29fe0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
29ff0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2a000 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2a010 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2a020 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2a030 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2a040 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2a050 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2a060 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2a070 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2a080 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2a090 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2a0a0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2a0b0 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2a0c0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2a0d0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2a0e0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2a0f0 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
2a100 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2a110 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
2a120 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
2a130 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
2a140 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a150 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
2a160 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
2a170 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
2a180 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
2a190 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
2a1a0 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
2a1b0 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
2a1c0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2a1d0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
2a1e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
2a1f0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
2a200 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
2a210 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
2a220 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
2a230 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
2a240 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
2a250 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
2a260 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
2a270 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
2a280 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
2a290 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
2a2a0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
2a2b0 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
2a2c0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
2a2d0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
2a2e0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
2a2f0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
2a300 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2a310 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2a320 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
2a330 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2a340 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
2a350 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2a360 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
2a370 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2a380 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2a390 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
2a3a0 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
2a3b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a3c0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
2a3d0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2a3e0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2a3f0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
2a400 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
2a410 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
2a420 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
2a430 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2a440 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
2a450 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
2a460 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
2a470 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
2a480 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
2a490 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
2a4a0 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
2a4b0 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
2a4c0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
2a4d0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
2a4e0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2a4f0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2a500 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2a510 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2a520 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a530 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2a540 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2a550 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2a560 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2a570 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2a580 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2a590 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2a5a0 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2a5b0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2a5c0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2a5d0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2a5e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2a5f0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2a600 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2a610 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2a620 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2a630 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2a640 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2a650 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2a660 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2a670 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2a680 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2a690 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2a6a0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2a6b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2a6c0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2a6d0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2a6e0 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2a6f0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2a700 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2a710 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2a720 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2a730 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2a740 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2a750 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2a760 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2a770 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2a780 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2a790 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2a7a0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2a7b0 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2a7c0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2a7d0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2a7e0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2a7f0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2a800 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2a810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a820 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2a830 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2a840 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2a850 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2a860 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2a870 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2a880 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2a890 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2a8a0 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2a8b0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a8c0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a8d0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2a8e0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2a8f0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2a900 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2a910 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2a920 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2a930 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2a940 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2a950 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2a960 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2a970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a980 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2a990 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2a9a0 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2a9b0 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2a9c0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2a9d0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2a9e0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2a9f0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2aa00 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2aa10 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2aa20 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2aa30 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2aa40 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2aa50 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2aa60 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2aa70 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2aa80 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2aa90 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2aaa0 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2aab0 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2aac0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2aad0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2aae0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2aaf0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ab00 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2ab10 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2ab20 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2ab30 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2ab40 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2ab50 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2ab60 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2ab70 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2ab80 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2ab90 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2aba0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2abb0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2abc0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2abd0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2abe0 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2abf0 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2ac00 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2ac10 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2ac20 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2ac30 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2ac40 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2ac50 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2ac60 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2ac70 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2ac80 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2ac90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2aca0 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2acb0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2acc0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2acd0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2ace0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2acf0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2ad00 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2ad10 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2ad20 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2ad30 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2ad40 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2ad50 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2ad60 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2ad70 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2ad80 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2ad90 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2ada0 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2adb0 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2adc0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2add0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2ade0 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2adf0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2ae00 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2ae10 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2ae20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2ae30 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2ae40 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2ae50 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2ae60 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2ae70 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2ae80 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2ae90 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2aea0 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2aeb0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2aec0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2aed0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2aee0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2aef0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2af00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2af10 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2af20 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2af30 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2af40 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2af50 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2af60 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2af70 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2af80 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2af90 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2afa0 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2afb0 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2afc0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2afd0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2afe0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2aff0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2b000 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2b010 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2b020 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2b030 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2b040 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2b050 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2b060 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2b070 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2b080 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2b090 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2b0a0 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2b0b0 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2b0c0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2b0d0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2b0e0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2b0f0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2b100 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2b110 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b120 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2b130 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b140 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2b150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2b160 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2b170 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2b180 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2b190 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2b1a0 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2b1b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b1c0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2b1d0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2b1e0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2b1f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b200 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2b210 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2b220 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2b230 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2b240 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2b250 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2b260 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2b270 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2b280 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2b290 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2b2a0 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2b2b0 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2b2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2b2d0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2b2e0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2b2f0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2b300 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2b310 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2b320 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2b330 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2b340 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2b350 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2b360 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2b370 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2b380 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2b390 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2b3a0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2b3b0 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2b3c0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2b3d0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2b3e0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2b3f0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2b400 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2b410 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2b420 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2b430 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2b440 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2b450 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2b460 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2b470 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2b480 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2b490 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2b4a0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2b4b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b4c0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2b4d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b4e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b4f0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2b500 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b510 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2b520 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2b530 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2b540 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b550 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b560 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2b570 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b580 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2b590 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2b5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b5b0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b5c0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2b5d0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2b5e0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  L sqlite3_bind_d
2b5f0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2b600 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2b610 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b620 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b630 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2b640 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2b650 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
2b660 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2b670 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2b680 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2b690 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b6a0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2b6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b6c0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2b6d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2b6e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2b6f0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2b700 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2b710 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2b720 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2b730 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2b740 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2b750 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2b760 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b770 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2b780 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2b790 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2b7a0 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2b7b0 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2b7c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2b7d0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b7e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b7f0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2b800 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2b810 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2b820 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2b830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2b840 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2b850 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2b860 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ding);.SQLITE_AP
2b870 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2b880 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2b890 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2b8a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b8b0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2b8c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b8d0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b8e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2b8f0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2b900 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2b910 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b920 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2b930 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2b940 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
2b950 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2b960 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f  ite3_uint64);../
2b970 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2b980 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
2b990 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f  ameters.** METHO
2b9a0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2b9b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
2b9c0 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ine can be used 
2b9d0 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
2b9e0 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d  er of [SQL param
2b9f0 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b  eters].** in a [
2ba00 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ba10 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65  nt].  SQL parame
2ba20 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20  ters are tokens 
2ba30 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22  of the.** form "
2ba40 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41  ?", "?NNN", ":AA
2ba50 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22  A", "$AAA", or "
2ba60 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65  @AAA" that serve
2ba70 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64   as.** placehold
2ba80 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74  ers for values t
2ba90 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33  hat are [sqlite3
2baa0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75  _bind_blob | bou
2bab0 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61  nd].** to the pa
2bac0 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61  rameters at a la
2bad0 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ter time..**.** 
2bae0 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61  ^(This routine a
2baf0 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20  ctually returns 
2bb00 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2bb10 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d   largest (rightm
2bb20 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65  ost).** paramete
2bb30 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73  r. For all forms
2bb40 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68   except ?NNN, th
2bb50 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f  is will correspo
2bb60 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d  nd to the.** num
2bb70 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61  ber of unique pa
2bb80 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61  rameters.  If pa
2bb90 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2bba0 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73  ?NNN form are us
2bbb0 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79  ed,.** there may
2bbc0 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20   be gaps in the 
2bbd0 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  list.)^.**.** Se
2bbe0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2bbf0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2bc00 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2bc10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bc20 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2bc30 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2bc40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2bc50 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2bc60 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2bc70 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bc80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2bc90 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2bca0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2bcb0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2bcc0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2bcd0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2bce0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2bcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2bd00 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2bd10 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
2bd20 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
2bd30 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
2bd40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
2bd50 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
2bd60 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2bd70 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
2bd80 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2bd90 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2bda0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2bdb0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
2bdc0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
2bdd0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
2bde0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2bdf0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
2be00 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
2be10 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
2be20 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
2be30 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
2be40 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
2be50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
2be60 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
2be70 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2be80 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
2be90 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
2bea0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
2beb0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
2bec0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
2bed0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
2bee0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
2bef0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2bf00 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
2bf10 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
2bf20 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
2bf30 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
2bf40 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
2bf50 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
2bf60 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
2bf70 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
2bf80 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
2bf90 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2bfa0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
2bfb0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
2bfc0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
2bfd0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
2bfe0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
2bff0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
2c000 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
2c010 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2c020 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
2c030 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2c040 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c050 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2c060 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2c070 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2c080 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c090 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2c0a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2c0b0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2c0c0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2c0d0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2c0e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2c0f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c100 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
2c110 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
2c120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
2c130 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
2c140 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
2c150 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
2c160 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c170 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2c180 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2c190 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2c1a0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2c1b0 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2c1c0 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2c1d0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2c1e0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2c1f0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2c200 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2c210 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2c220 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2c230 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2c240 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2c250 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2c260 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2c270 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2c280 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2c290 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2c2a0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2c2b0 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2c2c0 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2c2d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c2e0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2c2f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c300 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c310 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2c320 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c330 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2c340 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2c350 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c360 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2c370 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2c380 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2c390 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c3a0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2c3b0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2c3c0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2c3d0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2c3e0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2c3f0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2c400 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
2c410 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c420 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2c430 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2c440 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2c450 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2c460 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2c470 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c480 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2c490 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2c4a0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2c4b0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2c4c0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2c4d0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2c4e0 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
2c4f0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2c500 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2c510 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  lear_bindings(sq
2c520 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2c530 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2c540 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73  umber Of Columns
2c550 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2c560 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2c570 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2c580 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
2c590 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2c5a0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
2c5b0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
2c5c0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2c5d0 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
2c5e0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2c5f0 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
2c600 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
2c610 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
2c620 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
2c630 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
2c640 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
2c650 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
2c660 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  ta_count()].*/.S
2c670 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2c680 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2c690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2c6a0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
2c6b0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2c6c0 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
2c6d0 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
2c6e0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2c6f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2c700 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2c710 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2c720 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2c730 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2c740 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2c750 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2c760 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2c770 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2c780 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2c790 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c7a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2c7b0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2c7c0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2c7d0 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2c7e0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2c7f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2c800 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2c810 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2c820 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2c830 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2c840 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2c850 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2c860 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2c870 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c880 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2c890 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2c8a0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2c8b0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2c8c0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2c8d0 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2c8e0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c8f0 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2c900 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2c910 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2c920 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2c930 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2c940 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2c950 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2c960 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2c970 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2c980 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2c990 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2c9a0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2c9b0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2c9c0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2c9d0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2c9e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c9f0 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2ca00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2ca10 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2ca20 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2ca30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2ca40 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2ca50 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2ca60 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2ca70 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2ca80 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2ca90 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2caa0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2cab0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2cac0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2cad0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2cae0 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2caf0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2cb00 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2cb10 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2cb20 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2cb30 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2cb40 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2cb50 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2cb60 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2cb70 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2cb80 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2cb90 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2cba0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2cbb0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2cbc0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2cbd0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2cbe0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2cbf0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
2cc00 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2cc10 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
2cc20 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2cc30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2cc40 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2cc50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2cc60 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
2cc70 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
2cc80 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
2cc90 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2cca0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ccb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2ccc0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2ccd0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2cce0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2ccf0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2cd00 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2cd10 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2cd20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2cd30 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2cd40 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2cd50 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2cd60 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2cd70 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2cd80 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2cd90 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2cda0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2cdb0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2cdc0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2cdd0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2cde0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2cdf0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2ce00 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2ce10 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2ce20 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2ce30 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2ce40 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2ce50 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2ce60 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2ce70 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2ce80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ce90 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2cea0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2ceb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cec0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2ced0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2cee0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2cef0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2cf00 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2cf10 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2cf20 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2cf30 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2cf40 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2cf50 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2cf60 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2cf70 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2cf80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2cf90 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2cfa0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2cfb0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2cfc0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2cfd0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2cfe0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2cff0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2d000 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2d010 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2d020 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d030 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2d040 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2d050 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2d060 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2d070 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2d080 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2d090 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2d0a0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2d0b0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2d0c0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2d0d0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2d0e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2d0f0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2d100 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2d110 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2d120 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2d130 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2d140 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2d150 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2d160 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2d170 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2d180 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2d190 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2d1a0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2d1b0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2d1c0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2d1d0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2d1e0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2d1f0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2d200 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2d210 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2d220 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2d230 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2d240 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2d250 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2d260 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2d270 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2d280 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2d290 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2d2a0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2d2b0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2d2c0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2d2d0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2d2e0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2d2f0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2d300 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2d310 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2d320 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2d330 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2d340 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2d350 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2d360 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2d370 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d380 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d390 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2d3a0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2d3b0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2d3c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2d3d0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2d3e0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d3f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2d400 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2d410 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2d420 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2d430 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2d440 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d450 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2d460 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2d470 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2d480 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2d490 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d4a0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2d4b0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2d4c0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d4d0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2d4e0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2d4f0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2d500 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d510 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2d520 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2d530 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d540 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d550 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2d560 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2d570 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d580 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d590 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2d5a0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2d5b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d5c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2d5d0 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ble_name(sqlite3
2d5e0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d5f0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d600 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2d610 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2d620 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2d630 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d640 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d650 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2d660 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d670 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2d680 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d690 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d6a0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2d6b0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d6c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d6d0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2d6e0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2d6f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d700 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2d710 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2d720 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ult.** METHOD: s
2d730 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d740 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2d750 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2d760 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d770 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2d780 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2d790 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2d7a0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2d7b0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2d7c0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2d7d0 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2d7e0 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2d7f0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2d800 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2d810 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2d820 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2d830 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2d840 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2d850 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2d860 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2d870 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2d880 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2d890 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2d8a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2d8b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2d8c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2d8d0 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2d8e0 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2d8f0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2d900 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2d910 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2d920 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2d930 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2d940 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2d950 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2d960 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2d970 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2d980 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2d990 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2d9a0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2d9b0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2d9c0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2d9d0 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2d9e0 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2d9f0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2da00 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2da10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2da20 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2da30 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2da40 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2da50 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2da60 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2da70 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2da80 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2da90 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2daa0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2dab0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2dac0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2dad0 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2dae0 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2daf0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2db00 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2db10 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2db20 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2db30 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2db40 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2db50 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2db60 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2db70 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2db80 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2db90 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
2dba0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51  I const char *SQ
2dbb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2dbc0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c  ite3_column_decl
2dbd0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
2dbe0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2dbf0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2dc00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2dc10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2dc20 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2dc30 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2dc40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2dc50 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2dc60 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
2dc70 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2dc80 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
2dc90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dca0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
2dcb0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
2dcc0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2dcd0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2dce0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2dcf0 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
2dd00 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
2dd10 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
2dd20 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
2dd30 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2dd40 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
2dd50 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
2dd60 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
2dd70 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
2dd80 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
2dd90 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
2dda0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
2ddb0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
2ddc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
2ddd0 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
2dde0 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
2ddf0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
2de00 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
2de10 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
2de20 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
2de30 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2de40 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2de50 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
2de60 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
2de70 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
2de80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2de90 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2dea0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
2deb0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
2dec0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
2ded0 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
2dee0 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
2def0 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
2df00 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2df10 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
2df20 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
2df30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
2df40 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2df50 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
2df60 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
2df70 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
2df80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
2df90 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
2dfa0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2dfb0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
2dfc0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
2dfd0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2dfe0 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
2dff0 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
2e000 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
2e010 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
2e020 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2e030 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
2e040 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
2e050 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2e060 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
2e070 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
2e080 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
2e090 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
2e0a0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
2e0b0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
2e0c0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
2e0d0 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
2e0e0 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
2e0f0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
2e100 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
2e110 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
2e120 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
2e130 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2e140 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
2e150 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
2e160 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
2e170 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
2e180 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
2e190 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
2e1a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
2e1b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
2e1c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
2e1d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
2e1e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
2e1f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
2e200 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
2e210 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
2e220 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
2e230 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2e240 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
2e250 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
2e260 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
2e270 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
2e280 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
2e290 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
2e2a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
2e2b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
2e2c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
2e2d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
2e2e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
2e2f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
2e300 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
2e310 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
2e320 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
2e330 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
2e340 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
2e350 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
2e360 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
2e370 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
2e380 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
2e390 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
2e3a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2e3b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
2e3c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
2e3d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
2e3e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2e3f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
2e400 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
2e410 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
2e420 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
2e430 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
2e440 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
2e450 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2e460 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2e470 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
2e480 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
2e490 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
2e4a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2e4b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
2e4c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
2e4d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
2e4e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2e4f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
2e500 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
2e510 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
2e520 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
2e530 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
2e540 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
2e550 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
2e560 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2e570 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
2e580 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
2e590 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
2e5a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2e5b0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
2e5c0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2e5d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
2e5e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
2e5f0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
2e600 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
2e610 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
2e620 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
2e630 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
2e640 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
2e650 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
2e660 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
2e670 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2e680 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
2e690 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
2e6a0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2e6b0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
2e6c0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
2e6d0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
2e6e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
2e6f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
2e700 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
2e710 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
2e720 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
2e730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
2e740 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
2e750 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
2e760 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
2e770 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
2e780 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
2e790 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2e7a0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
2e7b0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
2e7c0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
2e7d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e7e0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
2e7f0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
2e800 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
2e810 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
2e820 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
2e830 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
2e840 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
2e850 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
2e860 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
2e870 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
2e880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2e890 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
2e8a0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
2e8b0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
2e8c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
2e8d0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
2e8e0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
2e8f0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
2e900 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
2e910 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
2e920 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
2e930 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
2e940 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
2e950 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
2e960 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
2e970 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2e980 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
2e990 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
2e9a0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
2e9b0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
2e9c0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
2e9d0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
2e9e0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
2e9f0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
2ea00 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
2ea10 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
2ea20 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
2ea30 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
2ea40 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
2ea50 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
2ea60 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
2ea70 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
2ea80 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
2ea90 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
2eaa0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
2eab0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
2eac0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
2ead0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
2eae0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
2eaf0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
2eb00 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
2eb10 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
2eb20 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
2eb30 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
2eb40 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
2eb50 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
2eb60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2eb70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb80 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
2eb90 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
2eba0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
2ebb0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
2ebc0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
2ebd0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
2ebe0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
2ebf0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
2ec00 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
2ec10 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
2ec20 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
2ec30 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
2ec40 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
2ec50 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
2ec60 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
2ec70 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
2ec80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2ec90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2eca0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
2ecb0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
2ecc0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
2ecd0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
2ece0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2ecf0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
2ed00 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
2ed10 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
2ed20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
2ed30 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
2ed40 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
2ed50 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
2ed60 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
2ed70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
2ed80 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2ed90 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2eda0 4c 4c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  LL sqlite3_step(
2edb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2edc0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2edd0 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   Number of colum
2ede0 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73  ns in a result s
2edf0 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2ee00 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2ee10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2ee20 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2ee30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2ee40 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2ee50 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2ee60 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2ee70 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2ee80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ee90 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2eea0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2eeb0 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2eec0 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2eed0 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2eee0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2eef0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2ef00 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2ef10 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2ef20 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2ef30 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ef40 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2ef50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ef60 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2ef70 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
2ef80 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
2ef90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
2efa0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2efb0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2efc0 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2efd0 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
2efe0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2eff0 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
2f000 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
2f010 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2f020 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
2f030 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
2f040 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
2f050 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
2f060 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2f070 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
2f080 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
2f090 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
2f0a0 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
2f0b0 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
2f0c0 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
2f0d0 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
2f0e0 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
2f0f0 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
2f100 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
2f110 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
2f120 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
2f130 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
2f140 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
2f150 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2f160 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f170 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f190 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f1a0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2f1b0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2f1c0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2f1d0 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2f1e0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2f1f0 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2f200 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2f210 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2f220 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2f230 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2f240 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2f250 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2f260 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2f270 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2f280 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2f290 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2f2a0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2f2b0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2f2c0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2f2d0 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2f2e0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2f2f0 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2f300 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2f310 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2f320 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2f330 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2f340 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2f350 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2f360 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2f370 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2f380 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2f390 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2f3a0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2f3b0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2f3c0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2f3d0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2f3e0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2f3f0 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2f400 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2f410 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2f420 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2f430 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2f440 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2f450 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2f460 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2f470 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2f480 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2f490 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2f4a0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2f4b0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2f4c0 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2f4d0 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2f4e0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2f4f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2f500 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2f510 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2f520 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2f530 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2f540 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2f550 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2f560 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2f570 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2f580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2f590 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2f5a0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2f5b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2f5c0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2f5d0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2f5e0 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2f5f0 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2f600 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2f610 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2f620 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2f630 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2f640 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f650 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f660 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2f670 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2f680 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2f690 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2f6a0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2f6b0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2f6c0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2f6d0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2f6e0 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2f6f0 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2f700 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2f710 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f720 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2f730 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2f740 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2f750 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2f760 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2f770 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2f780 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2f790 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2f7a0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2f7b0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2f7c0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2f7d0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2f7e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2f7f0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f800 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2f810 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2f820 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2f830 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f840 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2f850 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2f860 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2f870 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2f880 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2f890 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f8a0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2f8b0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f8c0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f8d0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2f8e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f8f0 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2f900 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2f910 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2f920 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2f930 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2f940 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2f950 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f960 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2f970 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f980 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2f990 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2f9a0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2f9b0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f9c0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2f9d0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2f9e0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f9f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2fa00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2fa10 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2fa20 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2fa30 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2fa40 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2fa50 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2fa60 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2fa70 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2fa80 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2fa90 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2faa0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2fab0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2fac0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2fad0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2fae0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2faf0 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2fb00 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2fb10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2fb20 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2fb30 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2fb40 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2fb50 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2fb60 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2fb70 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2fb80 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2fb90 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2fba0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2fbb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2fbc0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2fbd0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2fbe0 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2fbf0 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2fc00 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2fc10 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2fc20 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2fc30 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2fc40 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2fc50 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2fc60 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2fc70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2fc80 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2fc90 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2fca0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2fcb0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2fcc0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2fcd0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2fce0 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2fcf0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fd00 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2fd10 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2fd20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2fd30 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2fd40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2fd50 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2fd60 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2fd70 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2fd80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2fd90 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2fda0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2fdb0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2fdc0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2fdd0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2fde0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2fdf0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2fe00 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2fe10 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2fe20 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2fe30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2fe40 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2fe50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fe60 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2fe70 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2fe80 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2fe90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2fea0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2feb0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2fec0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2fed0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2fee0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2fef0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2ff00 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2ff10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2ff20 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2ff30 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2ff40 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2ff50 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ff60 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2ff70 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2ff80 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2ff90 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2ffa0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2ffb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2ffc0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2ffd0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2ffe0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2fff0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
30000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
30010 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
30020 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
30030 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
30040 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
30050 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
30060 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
30070 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
30080 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
30090 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
300a0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
300b0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
300c0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
300d0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
300e0 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
300f0 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
30100 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
30110 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
30120 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
30130 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30140 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
30150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30160 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
30170 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
30180 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
30190 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
301a0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
301b0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
301c0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
301d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
301e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
301f0 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
30200 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
30210 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
30220 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
30230 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
30240 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
30250 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
30260 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
30270 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
30280 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
30290 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
302a0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
302b0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
302c0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
302d0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
302e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
302f0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
30300 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
30310 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
30320 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
30330 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
30340 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
30350 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
30360 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
30370 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
30380 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
30390 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
303a0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
303b0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
303c0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
303d0 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
303e0 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
303f0 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
30400 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
30410 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
30420 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
30430 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30440 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
30450 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
30460 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
30470 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
30480 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
30490 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
304a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
304b0 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
304c0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
304d0 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
304e0 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
304f0 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
30500 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
30510 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
30520 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
30530 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
30540 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
30550 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
30560 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
30570 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
30580 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
30590 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
305a0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
305b0 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
305c0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
305d0 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
305e0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
305f0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
30600 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
30610 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
30620 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
30630 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
30640 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
30650 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
30660 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
30670 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
30680 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
30690 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
306a0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
306b0 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
306c0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
306d0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
306e0 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
306f0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
30700 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
30710 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
30720 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
30730 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
30740 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
30750 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30760 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
30770 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
30780 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30790 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
307a0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
307b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
307c0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
307d0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
307e0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
307f0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
30800 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
30810 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
30820 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30830 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30840 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
30850 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
30860 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
30870 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
30880 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
30890 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
308a0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
308b0 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
308c0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
308d0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
308e0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
308f0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
30900 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30910 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30920 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
30930 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
30940 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
30950 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
30960 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
30970 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
30980 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
30990 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
309a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
309b0 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
309c0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
309d0 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
309e0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
309f0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30a00 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
30a10 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
30a20 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
30a30 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
30a40 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
30a50 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
30a60 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
30a70 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
30a80 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
30a90 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30aa0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
30ab0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30ac0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
30ad0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30ae0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
30af0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
30b00 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
30b10 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
30b20 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
30b30 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
30b40 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
30b50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
30b60 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30b70 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
30b80 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30b90 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
30ba0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30bb0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30bc0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
30bd0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
30be0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
30bf0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
30c00 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
30c10 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
30c20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
30c30 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
30c40 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30c50 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
30c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30c70 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30c80 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
30c90 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
30ca0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
30cb0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
30cc0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30cd0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
30ce0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
30cf0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
30d00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
30d10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
30d20 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
30d30 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
30d40 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
30d50 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
30d60 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
30d70 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
30d80 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
30d90 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
30da0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
30db0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
30dc0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
30dd0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
30de0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
30df0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
30e00 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
30e10 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
30e20 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
30e30 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
30e40 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
30e50 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
30e60 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
30e70 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
30e80 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
30e90 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
30ea0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
30eb0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
30ec0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
30ed0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
30ee0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
30ef0 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
30f00 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
30f10 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
30f20 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
30f30 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
30f40 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
30f50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30f60 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
30f70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30f80 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
30f90 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
30fa0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
30fb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30fc0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
30fd0 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
30fe0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30ff0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
31000 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31010 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
31020 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
31030 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
31040 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
31050 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
31060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
31070 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
31080 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31090 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
310a0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
310b0 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
310c0 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
310d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
310e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
310f0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
31100 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
31110 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
31120 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
31130 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
31140 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
31150 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
31160 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
31170 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
31180 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
31190 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
311a0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
311b0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
311c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
311d0 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
311e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
311f0 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
31200 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
31210 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
31220 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
31230 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
31240 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
31250 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
31260 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31270 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
31280 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
31290 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
312a0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
312b0 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
312c0 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
312d0 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
312e0 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
312f0 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
31300 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
31310 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
31320 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
31330 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31340 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
31350 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
31360 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
31370 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
31380 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
31390 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
313a0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
313b0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
313c0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
313d0 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
313e0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
313f0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
31400 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
31410 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
31420 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
31430 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
31440 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
31450 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
31460 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
31470 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
31480 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
31490 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
314a0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
314b0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
314c0 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
314d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
314e0 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
314f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31500 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
31510 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
31520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31530 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31540 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31550 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
31560 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
31570 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
31580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31590 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
315a0 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51 4c 49  _API double SQLI
315b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
315c0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
315d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
315e0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
315f0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
31600 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
31610 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
31620 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31630 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31640 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
31650 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
31660 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31670 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
31680 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31690 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
316a0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 53 51 4c  signed char *SQL
316b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
316c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
316d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
316e0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
316f0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
31700 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
31710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31720 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
31730 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31740 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
31750 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
31760 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
31770 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31780 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31790 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
317a0 61 6c 75 65 20 2a 53 51 4c 49 54 45 5f 53 54 44  alue *SQLITE_STD
317b0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
317c0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
317d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
317e0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
317f0 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
31800 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
31810 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54  t Object.** DEST
31820 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f  RUCTOR: sqlite3_
31830 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
31840 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31850 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
31860 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20  alled to delete 
31870 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31880 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74  ement]..** ^If t
31890 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
318a0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65  valuation of the
318b0 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75   statement encou
318c0 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73  ntered no errors
318d0 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74  .** or if the st
318e0 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72  atement is never
318f0 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c   been evaluated,
31900 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69   then sqlite3_fi
31910 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73  nalize() returns
31920 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20  .** SQLITE_OK.  
31930 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
31940 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  ent evaluation o
31950 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61  f statement S fa
31960 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  iled, then.** sq
31970 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
31980 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70  ) returns the ap
31990 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
319a0 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78   code] or.** [ex
319b0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
319c0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  e]..**.** ^The s
319d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
319e0 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  S) routine can b
319f0 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20  e called at any 
31a00 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20  point during.** 
31a10 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f  the life cycle o
31a20 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
31a30 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66  ement] S:.** bef
31a40 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20  ore statement S 
31a50 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65  is ever evaluate
31a60 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20  d, after.** one 
31a70 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f  or more calls to
31a80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31a90 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79  )], or after any
31aa0 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c   call.** to [sql
31ab0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67  ite3_step()] reg
31ac0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
31ad0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74  er or not the st
31ae0 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63  atement has.** c
31af0 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69  ompleted executi
31b00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b  on..**.** ^Invok
31b10 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  ing sqlite3_fina
31b20 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c  lize() on a NULL
31b30 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61   pointer is a ha
31b40 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a  rmless no-op..**
31b50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
31b60 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a  ion must finaliz
31b70 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65  e every [prepare
31b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
31b90 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a  order to avoid.*
31ba0 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73  * resource leaks
31bb0 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76  .  It is a griev
31bc0 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68  ous error for th
31bd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
31be0 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61   try to use.** a
31bf0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
31c00 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
31c10 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e   been finalized.
31c20 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70    Any use of a p
31c30 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
31c40 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
31c50 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
31c60 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75   can result in u
31c70 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20  ndefined and.** 
31c80 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61  undesirable beha
31c90 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67  vior such as seg
31ca0 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20  faults and heap 
31cb0 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53  corruption..*/.S
31cc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
31cd0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
31ce0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
31cf0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
31d00 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
31d10 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
31d20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
31d30 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44  Object.** METHOD
31d40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
31d50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
31d60 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f  _reset() functio
31d70 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72  n is called to r
31d80 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64  eset a [prepared
31d90 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
31da0 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74  bject back to it
31db0 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c  s initial state,
31dc0 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d   ready to be re-
31dd0 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e  executed..** ^An
31de0 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  y SQL statement 
31df0 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68  variables that h
31e00 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20  ad values bound 
31e10 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a  to them using.**
31e20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
31e30 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  nd_blob | sqlite
31e40 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20  3_bind_*() API] 
31e50 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c  retain their val
31e60 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c  ues..** Use [sql
31e70 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
31e80 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20  ngs()] to reset 
31e90 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a  the bindings..**
31ea0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
31eb0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
31ec0 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65  rface resets the
31ed0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31ee0 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20  ment] S.** back 
31ef0 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
31f00 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e   of its program.
31f10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
31f20 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
31f30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
31f40 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
31f50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31f60 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20  ent] S returned 
31f70 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20  [SQLITE_ROW] or 
31f80 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a  [SQLITE_DONE],.*
31f90 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33  * or if [sqlite3
31fa0 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65  _step(S)] has ne
31fb0 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20  ver before been 
31fc0 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20  called on S,.** 
31fd0 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  then [sqlite3_re
31fe0 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20  set(S)] returns 
31ff0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
32000 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
32010 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
32020 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
32030 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
32040 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32050 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20   S indicated an 
32060 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b  error, then.** [
32070 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
32080 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70  ] returns an app
32090 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
320a0 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
320b0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
320c0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64  (S)] interface d
320d0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
320e0 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20  he values.** of 
320f0 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  any [sqlite3_bin
32100 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d  d_blob|bindings]
32110 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   on the [prepare
32120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a  d statement] S..
32130 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
32140 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
32150 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
32160 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
32170 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
32180 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
32190 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
321a0 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
321b0 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
321c0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
321d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
321e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
321f0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
32200 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
32210 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32220 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
32230 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
32240 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
32250 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
32260 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
32270 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
32280 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
32290 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
322a0 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
322b0 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
322c0 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
322d0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
322e0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
322f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
32300 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
32310 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
32320 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
32330 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
32340 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
32350 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
32360 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32370 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
32380 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
32390 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
323a0 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
323b0 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
323c0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
323d0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
323e0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
323f0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32400 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
32410 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
32420 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
32430 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
32440 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
32450 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
32460 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
32470 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
32480 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
32490 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
324a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
324b0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
324c0 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
324d0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
324e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
324f0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
32500 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
32510 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
32520 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
32530 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
32540 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
32550 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
32560 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
32570 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
32580 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
32590 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
325a0 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
325b0 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
325c0 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
325d0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
325e0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
325f0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
32600 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
32610 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
32620 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
32630 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
32640 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
32650 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
32660 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
32670 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
32680 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
32690 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
326a0 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
326b0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
326c0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
326d0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
326e0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
326f0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
32700 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
32710 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
32720 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
32730 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
32740 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
32750 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
32760 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
32770 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
32780 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
32790 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
327a0 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
327b0 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
327c0 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
327d0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
327e0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
327f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
32800 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
32810 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
32820 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
32830 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
32840 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
32850 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
32860 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
32870 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
32880 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
32890 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63  ers.  The applic
328a0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74  ation should set
328b0 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
328c0 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  to.** [SQLITE_UT
328d0 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75  F16LE] if the fu
328e0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
328f0 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a  ation invokes .*
32900 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
32910 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20  _text16le()] on 
32920 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51  an input, or [SQ
32930 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66  LITE_UTF16BE] if
32940 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
32950 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b  tation invokes [
32960 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32970 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20  xt16be()] on an 
32980 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51  input, or.** [SQ
32990 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b  LITE_UTF16] if [
329a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
329b0 78 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  xt16()] is used,
329c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38   or [SQLITE_UTF8
329d0 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20  ].** otherwise. 
329e0 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66   ^The same SQL f
329f0 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
32a00 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70  egistered multip
32a10 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a  le times using.*
32a20 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66  * different pref
32a30 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32a40 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65  ings, with diffe
32a50 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
32a60 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ions for.** each
32a70 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57   encoding..** ^W
32a80 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
32a90 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32aa0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32ab0 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32ac0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32ad0 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
32ae0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
32af0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
32b00 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
32b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
32b20 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  h parameter may 
32b30 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52  optionally be OR
32b40 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
32b50 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a  DETERMINISTIC].*
32b60 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74  * to signal that
32b70 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69   the function wi
32b80 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  ll always return
32b90 20 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74   the same result
32ba0 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61   given.** the sa
32bb0 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e  me inputs within
32bc0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
32bd0 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53  atement.  Most S
32be0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  QL functions are
32bf0 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69  .** deterministi
32c00 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e  c.  The built-in
32c10 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20   [random()] SQL 
32c20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65  function is an e
32c30 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66  xample of a.** f
32c40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20  unction that is 
32c50 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69  not deterministi
32c60 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71  c.  The SQLite q
32c70 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20  uery planner is 
32c80 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f  able to.** perfo
32c90 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70  rm additional op
32ca0 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64  timizations on d
32cb0 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e  eterministic fun
32cc0 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a  ctions, so use.*
32cd0 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
32ce0 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20  _DETERMINISTIC] 
32cf0 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e  flag is recommen
32d00 64 65 64 20 77 68 65 72 65 20 70 6f 73 73 69 62  ded where possib
32d10 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  le..**.** ^(The 
32d20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
32d30 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
32d40 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
32d50 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32d60 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
32d70 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
32d80 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
32d90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
32da0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32db0 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32dc0 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32dd0 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32de0 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
32df0 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
32e00 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
32e10 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
32e20 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
32e30 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32e40 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
32e50 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
32e60 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
32e70 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
32e80 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
32e90 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
32ea0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32eb0 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32ec0 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32ed0 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32ee0 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
32ef0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
32f00 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32f10 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32f20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
32f30 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
32f40 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
32f50 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
32f60 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
32f70 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
32f80 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
32f90 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
32fa0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32fb0 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32fc0 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32fd0 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32ff0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33000 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
33010 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
33020 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
33030 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
33040 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
33050 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
33060 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
33070 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
33080 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
33090 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
330a0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
330b0 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
330c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
330d0 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
330e0 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
330f0 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
33100 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
33110 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33120 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
33130 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
33140 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
33150 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
33160 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
33170 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
33180 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
33190 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
331a0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
331b0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
331c0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
331d0 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
331e0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
331f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33200 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
33210 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
33220 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
33230 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
33240 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33250 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
33260 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
33270 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
33280 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
33290 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
332a0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
332b0 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
332c0 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
332d0 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
332e0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
332f0 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
33300 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
33310 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
33320 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
33330 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
33340 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33350 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
33360 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
33370 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
33380 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
33390 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
333a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
333b0 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
333c0 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
333d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
333e0 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
333f0 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
33400 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
33410 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
33420 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
33430 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
33440 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
33450 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
33460 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
33470 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
33480 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
33490 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
334a0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
334b0 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
334c0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
334d0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
334e0 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
334f0 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
33500 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
33510 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
33520 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
33530 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
33540 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33550 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
33560 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
33570 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33580 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
33590 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
335a0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
335b0 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
335c0 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
335d0 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
335e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
335f0 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
33600 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
33610 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33620 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
33630 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
33640 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
33650 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
33660 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33670 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
33680 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
33690 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
336a0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
336b0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
336c0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
336d0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
336e0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
336f0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33700 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33710 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
33720 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33730 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33740 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
33750 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
33760 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
33770 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33780 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33790 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
337a0 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
337b0 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
337c0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
337d0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
337e0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
337f0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
33800 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
33810 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
33820 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
33830 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
33840 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33850 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33860 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33870 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
33880 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
33890 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
338a0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
338b0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
338c0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
338d0 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
338e0 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
338f0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
33900 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
33910 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
33920 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
33930 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33940 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33950 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
33960 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
33970 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33980 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33990 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
339a0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
339b0 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
339c0 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
339d0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
339e0 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
339f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
33a00 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
33a10 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
33a20 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
33a30 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
33a40 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
33a50 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
33a60 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
33a70 20 20 20 20 20 20 20 20 31 20 20 20 20 2f 2a 20          1    /* 
33a80 49 4d 50 3a 20 52 2d 33 37 35 31 34 2d 33 35 35  IMP: R-37514-355
33a90 36 36 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  66 */.#define SQ
33aa0 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
33ab0 20 20 20 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a      2    /* IMP:
33ac0 20 52 2d 30 33 33 37 31 2d 33 37 36 33 37 20 2a   R-03371-37637 *
33ad0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33ae0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
33af0 33 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35  3    /* IMP: R-5
33b00 31 39 37 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64  1971-34154 */.#d
33b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33b20 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
33b30 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
33b40 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
33b50 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
33b60 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
33b70 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
33b80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33b90 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
33ba0 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
33bb0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
33bc0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
33bd0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
33be0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
33bf0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
33c00 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
33c10 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
33c20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
33c30 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
33c40 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
33c50 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
33c60 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
33c70 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33c80 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
33c90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
33ca0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33cb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
33cc0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
33cd0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
33ce0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
33cf0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33d00 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
33d10 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
33d20 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
33d30 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
33d40 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
33d50 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
33d60 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
33d70 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
33d80 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
33d90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
33da0 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
33db0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
33dc0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
33dd0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
33de0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
33df0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
33e00 73 2e 20 20 54 6f 20 65 6e 63 6f 75 72 61 67 65  s.  To encourage
33e10 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20   programmers to 
33e20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 73 65 20 66  avoid.** these f
33e30 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c  unctions, we wil
33e40 6c 20 6e 6f 74 20 65 78 70 6c 61 69 6e 20 77 68  l not explain wh
33e50 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
33e60 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
33e70 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
33e80 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
33e90 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
33ea0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
33eb0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33ec0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
33ed0 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
33ee0 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33ef0 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
33f00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33f10 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
33f20 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
33f30 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33f40 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
33f50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33f60 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
33f70 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
33f80 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
33f90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
33fa0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33fb0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
33fc0 4c 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  L sqlite3_global
33fd0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
33fe0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33ff0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
34000 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
34010 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
34020 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
34030 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
34040 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
34050 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
34060 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
34070 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
34080 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
34090 69 6e 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20  int),.          
340a0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
340b0 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  *,sqlite3_int64)
340c0 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ;.#endif../*.** 
340d0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
340e0 69 6e 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a  ing SQL Values.*
340f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
34100 33 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68  3_value.**.** Th
34110 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
34120 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
34130 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34140 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
34150 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
34160 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
34170 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
34180 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
34190 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
341a0 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
341b0 65 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  e.  .**.** The x
341c0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
341d0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
341e0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
341f0 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
34200 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
34210 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
34220 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
34230 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
34240 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
34250 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
34260 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
34270 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
34280 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
34290 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
342a0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
342b0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
342c0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
342d0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
342e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
342f0 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
34300 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
34310 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
34320 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
34330 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
34340 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
34350 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
34360 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
34370 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
34380 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
34390 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
343a0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
343b0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
343c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
343d0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
343e0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
343f0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
34400 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
34410 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
34420 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
34430 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
34440 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
34450 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
34460 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
34470 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
34480 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
34490 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
344a0 63 65 70 74 20 74 68 61 74 20 74 68 65 73 65 20  cept that these 
344b0 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
344c0 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
344d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
344e0 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
344f0 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
34500 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
34510 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
34520 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
34530 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
34540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34550 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
34560 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
34570 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
34580 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
34590 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
345a0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
345b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
345c0 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
345d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
345e0 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
345f0 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
34600 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
34610 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
34620 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
34630 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
34640 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
34650 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
34660 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
34670 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
34680 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
34690 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
346a0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
346b0 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
346c0 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
346d0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
346e0 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
346f0 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
34700 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
34710 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
34720 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
34730 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
34740 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
34750 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
34760 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
34770 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
34780 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
34790 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
347a0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
347b0 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
347c0 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
347d0 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
347e0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
347f0 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
34800 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
34810 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
34820 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
34830 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
34840 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
34850 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
34860 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
34870 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
34880 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34890 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
348a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
348b0 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
348c0 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
348d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
348e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
348f0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
34900 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34910 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
34920 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
34930 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
34940 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
34950 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34960 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
34970 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
34980 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
34990 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
349a0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
349b0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
349c0 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
349d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
349e0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
349f0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34a00 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
34a10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34a20 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
34a30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34a40 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71  3_value_bytes(sq
34a50 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34a60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34a70 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34a80 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
34a90 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
34aa0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  *);.SQLITE_API d
34ab0 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44  ouble SQLITE_STD
34ac0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34ad0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
34ae0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34af0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
34b00 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
34b10 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74  _value_int(sqlit
34b20 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34b30 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
34b40 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43  nt64 SQLITE_STDC
34b50 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34b60 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
34b70 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34b80 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
34b90 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  ed char *SQLITE_
34ba0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
34bb0 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69 74  value_text(sqlit
34bc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34bd0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34be0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
34bf0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34c00 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76  text16(sqlite3_v
34c10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34c20 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
34c30 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
34c40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34c50 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  16le(sqlite3_val
34c60 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34c70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
34c80 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
34c90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34ca0 62 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  be(sqlite3_value
34cb0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
34cc0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
34cd0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34ce0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34cf0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34d00 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34d10 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34d20 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
34d30 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34d40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34d50 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 56   Obtaining SQL V
34d60 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
34d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
34d80 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
34d90 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56  _value_subtype(V
34da0 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
34db0 6e 73 20 74 68 65 20 73 75 62 74 79 70 65 20 66  ns the subtype f
34dc0 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63  or.** an [applic
34dd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34de0 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75  L function] argu
34df0 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62  ment V.  The sub
34e00 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  type.** informat
34e10 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
34e20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65  to pass a limite
34e30 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74  d amount of cont
34e40 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  ext from.** one 
34e50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
34e60 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68  another.  Use th
34e70 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  e [sqlite3_resul
34e80 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20  t_subtype()].** 
34e90 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74  routine to set t
34ea0 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20 74  he subtype for t
34eb0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
34ec0 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  of an SQL functi
34ed0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
34ee0 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66   makes no use of
34ef0 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e   subtype itself.
34f00 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73    It merely pass
34f10 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a  es the subtype.*
34f20 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c  * from the resul
34f30 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63  t of one [applic
34f40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
34f50 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f  L function] into
34f60 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66   the.** input of
34f70 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 53 51 4c   another..*/.SQL
34f80 49 54 45 5f 41 50 49 20 75 6e 73 69 67 6e 65 64  ITE_API unsigned
34f90 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
34fa0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
34fb0 65 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65  e_subtype(sqlite
34fc0 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
34fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79  * CAPI3REF: Copy
34fe0 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61   And Free SQL Va
34ff0 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  lues.** METHOD: 
35000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a  sqlite3_value.**
35010 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35020 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e  _value_dup(V) in
35030 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
35040 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
35050 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
35060 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75  bject D and retu
35070 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
35080 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68   that copy.  ^Th
35090 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
350a0 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  ] returned.** is
350b0 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71   a [protected sq
350c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
350d0 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20  ect even if the 
350e0 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a  input is not..**
350f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
35100 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72  lue_dup(V) inter
35110 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
35120 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f  L if V is NULL o
35130 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79  r if a.** memory
35140 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
35150 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
35160 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65  lite3_value_free
35170 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72  (V) interface fr
35180 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f  ees an [sqlite3_
35190 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a  value] object.**
351a0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
351b0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
351c0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e  e3_value_dup()].
351d0 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c    ^If V is a NUL
351e0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  L pointer.** the
351f0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  n sqlite3_value_
35200 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72  free(V) is a har
35210 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
35220 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
35230 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 73  E_EXPERIMENTAL s
35240 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51  qlite3_value *SQ
35250 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35260 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 63  ite3_value_dup(c
35270 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
35280 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35290 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
352a0 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54 45  NTAL void SQLITE
352b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
352c0 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c 69  _value_free(sqli
352d0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a  te3_value*);../*
352e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
352f0 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46  tain Aggregate F
35300 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a  unction Context.
35310 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35320 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35330 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
35340 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
35350 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
35360 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
35370 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
35380 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
35390 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
353a0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
353b0 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
353c0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
353d0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
353e0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
353f0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
35400 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
35410 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
35420 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
35430 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
35440 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
35450 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
35460 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
35470 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
35480 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
35490 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
354a0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
354b0 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
354c0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
354d0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
354e0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
354f0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
35500 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
35510 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
35520 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
35530 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
35540 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
35550 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
35560 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
35570 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
35580 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
35590 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
355a0 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
355b0 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
355c0 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
355d0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
355e0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
355f0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
35600 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35610 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
35620 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
35630 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
35640 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
35650 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
35660 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35670 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
35680 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
35690 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
356a0 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
356b0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
356c0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
356d0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
356e0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
356f0 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77  LL pointer .** w
35700 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64  hen first called
35710 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68   if N is less th
35720 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
35730 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
35740 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65  ry.** allocate e
35750 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
35760 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
35770 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
35780 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
35790 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
357a0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
357b0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
357c0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
357d0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
357e0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
357f0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
35800 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
35810 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
35820 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
35830 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
35840 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
35850 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
35860 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
35870 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
35880 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74  location.)^  Wit
35890 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63  hin the xFinal c
358a0 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63  allback, it is c
358b0 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a  ustomary to set.
358c0 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20  ** N=0 in calls 
358d0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
358e0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
358f0 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a  ) so that no .**
35900 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72   pointless memor
35910 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63  y allocations oc
35920 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  cur..**.** ^SQLi
35930 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  te automatically
35940 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72   frees the memor
35950 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a  y allocated by .
35960 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
35970 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
35980 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74  hen the aggregat
35990 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65  e query conclude
359a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
359b0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73  st parameter mus
359c0 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74  t be a copy of t
359d0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
359e0 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e  ontext | SQL fun
359f0 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74  ction context] t
35a00 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74  hat is the first
35a10 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f   parameter.** to
35a20 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46   the xStep or xF
35a30 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f  inal callback ro
35a40 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65  utine that imple
35a50 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67  ments the aggreg
35a60 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ate.** function.
35a70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35a80 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
35a90 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
35aa0 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
35ab0 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74  .** the aggregat
35ac0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  e SQL function i
35ad0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
35ae0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
35af0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35b00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35b10 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
35b20 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
35b30 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
35b40 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
35b50 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
35b60 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35b70 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35b80 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
35b90 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
35ba0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
35bb0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
35bc0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
35bd0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
35be0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
35bf0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
35c00 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
35c10 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
35c20 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
35c30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35c40 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
35c50 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
35c60 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
35c70 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
35c80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
35c90 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35ca0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35cb0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35cc0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35cd0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35ce0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
35cf0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
35d00 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
35d10 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
35d20 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
35d30 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35d40 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
35d50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
35d60 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
35d70 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  unctions.** METH
35d80 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
35d90 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ext.**.** ^The s
35da0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
35db0 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
35dc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
35dd0 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
35de0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
35df0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e00 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
35e10 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
35e20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35e30 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
35e40 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
35e50 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
35e60 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
35e70 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
35e80 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
35e90 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
35ea0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
35eb0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
35ec0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
35ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35ee0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
35ef0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
35f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
35f10 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
35f20 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44  y Data.** METHOD
35f30 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
35f40 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  t.**.** These fu
35f50 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75  nctions may be u
35f60 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72  sed by (non-aggr
35f70 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74  egate) SQL funct
35f80 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
35f90 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
35fa0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
35fb0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
35fc0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
35fd0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
35fe0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
35ff0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
36000 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
36010 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
36020 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
36030 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
36040 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
36050 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
36060 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a  .  An example.**
36070 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d   of where this m
36080 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69  ight be useful i
36090 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65  s in a regular-e
360a0 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
360b0 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20  ng.** function. 
360c0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72  The compiled ver
360d0 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75  sion of the regu
360e0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
360f0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a  an be stored as.
36100 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f  ** metadata asso
36110 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
36120 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20  pattern string. 
36130 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e   .** Then as lon
36140 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e  g as the pattern
36150 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20   string remains 
36160 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65  the same,.** the
36170 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
36180 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
36190 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
361a0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
361b0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
361c0 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  e function..**.*
361d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
361e0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
361f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
36200 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
36210 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
36220 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71  ciated by the sq
36230 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36240 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  a() function wit
36250 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  h the Nth argume
36260 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74  nt.** value to t
36270 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36280 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
36290 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f   ^If there is no
362a0 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
362b0 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
362c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
362d0 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33  nt, this sqlite3
362e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
362f0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75  nterface.** retu
36300 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
36310 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
36320 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36330 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65  ta(C,N,P,X) inte
36340 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73  rface saves P as
36350 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
36360 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
36370 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
36380 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36390 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71  nction.  ^Subseq
363a0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
363b0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
363c0 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e  data(C,N) return
363d0 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74   P from the most
363e0 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74   recent.** sqlit
363f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
36400 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20  ,N,P,X) call if 
36410 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
36420 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a  still valid or.*
36430 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65  * NULL if the me
36440 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
36450 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41  discarded..** ^A
36460 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74  fter each call t
36470 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
36480 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77  xdata(C,N,P,X) w
36490 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55  here X is not NU
364a0 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  LL,.** SQLite wi
364b0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
364c0 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f  structor functio
364d0 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74  n X with paramet
364e0 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20  er P exactly.** 
364f0 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d  once, when the m
36500 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61  etadata is disca
36510 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  rded..** SQLite 
36520 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61  is free to disca
36530 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  rd the metadata 
36540 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63  at any time, inc
36550 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20  luding: <ul>.** 
36560 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f  <li> when the co
36570 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63  rresponding func
36580 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63  tion parameter c
36590 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c  hanges, or.** <l
365a0 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  i> when [sqlite3
365b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
365c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
365d0 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20  ] is called for 
365e0 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20  the.**      SQL 
365f0 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a  statement, or.**
36600 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74   <li> when sqlit
36610 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
36620 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69   is invoked agai
36630 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61  n on the same pa
36640 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c  rameter, or.** <
36650 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f  li> during the o
36660 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f  riginal sqlite3_
36670 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61  set_auxdata() ca
36680 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79  ll when a memory
36690 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61   .**      alloca
366a0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
366b0 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  s. </ul>)^.**.**
366c0 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62   Note the last b
366d0 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75  ullet in particu
366e0 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75  lar.  The destru
366f0 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71  ctor X in .** sq
36700 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
36710 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74  a(C,N,P,X) might
36720 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64   be called immed
36730 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74  iately, before t
36740 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65  he.** sqlite3_se
36750 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
36760 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72  rface even retur
36770 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74  ns.  Hence sqlit
36780 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
36790 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61  .** should be ca
367a0 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e  lled near the en
367b0 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  d of the functio
367c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
367d0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63   and the.** func
367e0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
367f0 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d  ion should not m
36800 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50  ake any use of P
36810 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65   after.** sqlite
36820 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
36830 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e  has been called.
36840 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
36850 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
36860 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
36870 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
36880 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ls for.** functi
36890 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  on parameters th
368a0 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74  at are compile-t
368b0 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69  ime constants, i
368c0 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c  ncluding literal
368d0 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b  .** values and [
368e0 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20  parameters] and 
368f0 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70  expressions comp
36900 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  osed from the sa
36910 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  me.)^.**.** Thes
36920 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
36930 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
36940 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
36950 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
36960 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
36970 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
36980 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
36990 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
369a0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
369b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
369c0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
369d0 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
369e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
369f0 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  set_auxdata(sqli
36a00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36a10 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64  t N, void*, void
36a20 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a   (*)(void*));...
36a30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36a40 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69  Constants Defini
36a50 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72  ng Special Destr
36a60 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a  uctor Behavior.*
36a70 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73  *.** These are s
36a80 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f  pecial values fo
36a90 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  r the destructor
36aa0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
36ab0 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e  in as the.** fin
36ac0 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72  al argument to r
36ad0 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
36ae0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36af0 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64  b()].  ^If the d
36b00 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67  estructor.** arg
36b10 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f  ument is SQLITE_
36b20 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73  STATIC, it means
36b30 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e   that the conten
36b40 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e  t pointer is con
36b50 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c  stant.** and wil
36b60 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20  l never change. 
36b70 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65   It does not nee
36b80 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
36b90 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49  d.  ^The.** SQLI
36ba0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c  TE_TRANSIENT val
36bb0 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  ue means that th
36bc0 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c  e content will l
36bd0 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a  ikely change in.
36be0 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75  ** the near futu
36bf0 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69  re and that SQLi
36c00 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69  te should make i
36c10 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
36c20 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f  opy of.** the co
36c30 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74  ntent before ret
36c40 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  urning..**.** Th
36c50 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63  e typedef is nec
36c60 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61  essary to work a
36c70 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69  round problems i
36c80 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b  n certain.** C++
36c90 20 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74   compilers..*/.t
36ca0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
36cb0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
36cc0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
36cd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
36ce0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
36cf0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
36d00 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
36d10 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
36d20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
36d30 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
36d40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36d50 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
36d60 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
36d70 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44  nction.** METHOD
36d80 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
36d90 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  t.**.** These ro
36da0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
36db0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
36dc0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
36dd0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
36de0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
36df0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
36e00 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
36e10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36e20 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
36e30 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
36e40 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
36e50 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
36e60 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
36e70 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
36e80 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
36e90 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
36ea0 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
36eb0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
36ec0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
36ed0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
36ee0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
36ef0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
36f00 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
36f10 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
36f20 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
36f30 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
36f40 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
36f50 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36f60 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
36f70 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
36f80 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
36f90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
36fa0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
36fb0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
36fc0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
36fd0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
36fe0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
36ff0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
37000 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
37010 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
37020 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
37030 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37040 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
37050 28 43 2c 4e 29 20 61 6e 64 20 73 71 6c 69 74 65  (C,N) and sqlite
37060 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
37070 62 36 34 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65  b64(C,N).** inte
37080 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
37090 65 73 75 6c 74 20 6f 66 20 74 68 65 20 61 70 70  esult of the app
370a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
370b0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
370c0 2a 2a 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  ** a BLOB contai
370d0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79  ning all zero by
370e0 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20  tes and N bytes 
370f0 69 6e 20 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e  in size..**.** ^
37100 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37110 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65  lt_double() inte
37120 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
37130 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
37140 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37150 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37160 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70   be a floating p
37170 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69  oint value speci
37180 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32  fied.** by its 2
37190 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
371a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
371b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
371c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
371d0 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63  t_error16() func
371e0 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74  tions.** cause t
371f0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53  he implemented S
37200 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74  QL function to t
37210 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f  hrow an exceptio
37220 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  n..** ^SQLite us
37230 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f  es the string po
37240 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a  inted to by the.
37250 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ** 2nd parameter
37260 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75   of sqlite3_resu
37270 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71  lt_error() or sq
37280 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37290 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65  or16().** as the
372a0 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f   text of an erro
372b0 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c  r message.  ^SQL
372c0 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
372d0 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
372e0 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  age string from 
372f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37300 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e  rror() as UTF-8.
37310 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65   ^SQLite.** inte
37320 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e  rprets the strin
37330 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
37340 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
37350 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74  as UTF-16 in nat
37360 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65  ive.** byte orde
37370 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72  r.  ^If the thir
37380 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
37390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
373a0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
373b0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
373c0 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  16() is negative
373d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
373e0 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a  es as the error.
373f0 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74  ** message all t
37400 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74  ext up through t
37410 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
37420 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
37430 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
37440 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
37450 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
37460 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
37470 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
37480 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65  non-negative the
37490 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74  n SQLite takes t
374a0 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65  hat many.** byte
374b0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
374c0 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  s) from the 2nd 
374d0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
374e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
374f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37500 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
37510 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
37520 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72  t_error16().** r
37530 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70  outines make a p
37540 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
37550 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
37560 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20   text before.** 
37570 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65  they return.  He
37580 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  nce, the calling
37590 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65   function can de
375a0 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d  allocate or.** m
375b0 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61  odify the text a
375c0 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e  fter they return
375d0 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a   without harm..*
375e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
375f0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
37600 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e  () function chan
37610 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ges the error co
37620 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  de.** returned b
37630 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65  y SQLite as a re
37640 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  sult of an error
37650 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20   in a function. 
37660 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a   ^By default,.**
37670 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
37680 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  is SQLITE_ERROR.
37690 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20    ^A subsequent 
376a0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
376b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
376c0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
376d0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65  ult_error16() re
376e0 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63  sets the error c
376f0 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52  ode to SQLITE_ER
37700 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ROR..**.** ^The 
37710 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37720 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e  rror_toobig() in
37730 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
37740 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
37750 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
37760 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
37770 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
37780 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
37790 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
377a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
377b0 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e  error_nomem() in
377c0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
377d0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
377e0 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63  n.** error indic
377f0 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d  ating that a mem
37800 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
37810 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ailed..**.** ^Th
37820 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37830 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65  _int() interface
37840 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
37850 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
37860 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37870 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37880 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73   be the 32-bit s
37890 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
378a0 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20   value given in 
378b0 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  the 2nd argument
378c0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
378d0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29  3_result_int64()
378e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
378f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37900 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
37910 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37920 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37930 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  e 64-bit signed 
37940 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
37950 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
37960 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
37970 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37980 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74  esult_null() int
37990 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
379a0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
379b0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
379c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
379d0 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a  ion to be NULL..
379e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
379f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29  e3_result_text()
37a00 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  , sqlite3_result
37a10 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71  _text16(),.** sq
37a20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37a30 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c  t16le(), and sql
37a40 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37a50 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65  16be() interface
37a60 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74  s.** set the ret
37a70 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
37a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37a90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
37aa0 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74   be.** a text st
37ab0 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65  ring which is re
37ac0 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46  presented as UTF
37ad0 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76  -8, UTF-16 nativ
37ae0 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a  e byte order,.**
37af0 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65   UTF-16 little e
37b00 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36  ndian, or UTF-16
37b10 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73   big endian, res
37b20 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54  pectively..** ^T
37b30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37b40 74 5f 74 65 78 74 36 34 28 29 20 69 6e 74 65 72  t_text64() inter
37b50 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
37b60 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e  turn value of an
37b70 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  .** application-
37b80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37b90 20 74 6f 20 62 65 20 61 20 74 65 78 74 20 73 74   to be a text st
37ba0 72 69 6e 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64  ring in an encod
37bb0 69 6e 67 0a 2a 2a 20 73 70 65 63 69 66 69 65 64  ing.** specified
37bc0 20 62 79 20 74 68 65 20 66 69 66 74 68 20 28 61   by the fifth (a
37bd0 6e 64 20 6c 61 73 74 29 20 70 61 72 61 6d 65 74  nd last) paramet
37be0 65 72 2c 20 77 68 69 63 68 20 6d 75 73 74 20 62  er, which must b
37bf0 65 20 6f 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c  e one.** of [SQL
37c00 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49  ITE_UTF8], [SQLI
37c10 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49  TE_UTF16], [SQLI
37c20 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20  TE_UTF16BE], or 
37c30 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37c40 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b  ..** ^SQLite tak
37c50 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73 75  es the text resu
37c60 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c  lt from the appl
37c70 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20  ication from.** 
37c80 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37c90 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
37ca0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
37cb0 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66  terfaces..** ^If
37cc0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
37cd0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
37ce0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
37cf0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20  nterfaces.** is 
37d00 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53  negative, then S
37d10 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73 75  QLite takes resu
37d20 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65  lt text from the
37d30 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a   2nd parameter.*
37d40 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  * through the fi
37d50 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
37d60 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  er..** ^If the 3
37d70 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
37d80 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37d90 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37da0 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65  ces.** is non-ne
37db0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20  gative, then as 
37dc0 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20  many bytes (not 
37dd0 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20 74  characters) of t
37de0 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74  he text.** point
37df0 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64  ed to by the 2nd
37e00 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20 74   parameter are t
37e10 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c  aken as the appl
37e20 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a  ication-defined.
37e30 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75  ** function resu
37e40 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64 20  lt.  If the 3rd 
37e50 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
37e60 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
37e70 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68  it.** must be th
37e80 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e  e byte offset in
37e90 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  to the string wh
37ea0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
37eb0 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20  inator would.** 
37ec0 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73 74  appear if the st
37ed0 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74  ring where NUL t
37ee0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
37ef0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
37f00 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  s occur.** in th
37f10 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62 79  e string at a by
37f20 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20 69  te offset that i
37f30 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20  s less than the 
37f40 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64  value of the 3rd
37f50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74  .** parameter, t
37f60 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e  hen the resultin
37f70 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f  g string will co
37f80 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e  ntain embedded N
37f90 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72  ULs and the.** r
37fa0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
37fb0 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f  ions operating o
37fc0 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20 65  n strings with e
37fd0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
37fe0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49  undefined..** ^I
37ff0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
38000 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
38010 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
38020 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
38030 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38040 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55  blob is a non-NU
38050 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
38060 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68   SQLite calls th
38070 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61  at.** function a
38080 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  s the destructor
38090 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20   on the text or 
380a0 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e  BLOB result when
380b0 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73   it has.** finis
380c0 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
380d0 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
380e0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
380f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
38100 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
38110 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20  rfaces or to.** 
38120 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
38130 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
38140 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
38150 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20  TE_STATIC, then 
38160 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65  SQLite.** assume
38170 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74 20  s that the text 
38180 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69  or BLOB result i
38190 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70  s in constant sp
381a0 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
381b0 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e  .** copy the con
381c0 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61  tent of the para
381d0 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61  meter nor call a
381e0 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
381f0 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68  he content.** wh
38200 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  en it has finish
38210 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65  ed using that re
38220 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  sult..** ^If the
38230 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
38240 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
38250 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
38260 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
38270 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
38280 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
38290 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54  onstant SQLITE_T
382a0 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e  RANSIENT.** then
382b0 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20   SQLite makes a 
382c0 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73 75  copy of the resu
382d0 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62  lt into space ob
382e0 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66  tained from.** f
382f0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38300 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74  loc()] before it
38310 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
38320 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
38330 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
38340 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
38350 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
38360 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
38370 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
38380 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
38390 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
383a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
383b0 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
383c0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
383d0 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
383e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
383f0 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
38400 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
38410 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
38420 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
38430 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
38440 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
38450 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
38460 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
38470 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
38480 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
38490 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
384a0 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
384b0 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
384c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
384d0 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
384e0 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
384f0 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
38500 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
38510 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
38520 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
38530 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
38540 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
38550 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
38560 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
38570 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
38580 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
38590 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
385a0 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
385b0 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
385c0 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
385d0 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
385e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
385f0 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
38600 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
38610 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
38620 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
38630 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
38640 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
38650 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
38660 4c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  L sqlite3_result
38670 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
38680 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
38690 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
386a0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
386b0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
386c0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
386d0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 36 34 28  3_result_blob64(
386e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
386f0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 0a 20 20  ,const void*,.  
38700 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
38710 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
38720 5f 75 69 6e 74 36 34 2c 76 6f 69 64 28 2a 29 28  _uint64,void(*)(
38730 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
38740 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
38750 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
38760 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71  result_double(sq
38770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38780 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
38790 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
387a0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
387b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c  result_error(sql
387c