System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact d6d9b263bb82f21535be8891cfcbb84d0b59360f:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 33 2e 31 31 2e 31 22 0a 23 64       "3.11.1".#d
10b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52  efine SQLITE_VER
10c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30 31 31  SION_NUMBER 3011
10d0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#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 36 2d 30 33 2d 30 33 20 31 36    "2016-03-03 16
1100: 3a 31 37 3a 35 33 20 66 30 34 37 39 32 30 63 65  :17:53 f047920ce
1110: 31 36 39 37 31 65 35 37 33 62 63 36 65 63 39 61  16971e573bc6ec9a
1120: 34 38 62 31 31 38 63 39 64 65 32 62 33 61 37 22  48b118c9de2b3a7"
1130: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1140: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1150: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
1160: 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  rs.** KEYWORDS: 
1170: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c  sqlite3_version,
1180: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
1190: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11a0: 74 65 72 66 61 63 65 73 20 70 72 6f 76 69 64 65  terfaces provide
11b0: 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d   the same inform
11c0: 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51  ation as the [SQ
11d0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a  LITE_VERSION],.*
11e0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
11f0: 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b  N_NUMBER], and [
1200: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1210: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1220: 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61   macros.** but a
1230: 72 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  re associated wi
1240: 74 68 20 74 68 65 20 6c 69 62 72 61 72 79 20 69  th the library i
1250: 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 68 65  nstead of the he
1260: 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61  ader file.  ^(Ca
1270: 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61  utious.** progra
1280: 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c  mmers might incl
1290: 75 64 65 20 61 73 73 65 72 74 28 29 20 73 74 61  ude assert() sta
12a0: 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72  tements in their
12b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
12c0: 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74 20 76  ** verify that v
12d0: 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
12e0: 79 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  y these interfac
12f0: 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63  es match the mac
1300: 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65  ros in.** the he
1310: 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65  ader, and thus e
1320: 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
1330: 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a  pplication is.**
1340: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d   compiled with m
1350: 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20  atching library 
1360: 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c 65 73  and header files
1370: 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  ..**.** <blockqu
1380: 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73  ote><pre>.** ass
1390: 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62  ert( sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
13b0: 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ==SQLITE_VERSION
13c0: 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73  _NUMBER );.** as
13d0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
13e0: 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c  ite3_sourceid(),
13f0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1400: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72  )==0 );.** asser
1410: 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65  t( strcmp(sqlite
1420: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53  3_libversion(),S
1430: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d  QLITE_VERSION)==
1440: 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  0 );.** </pre></
1450: 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1460: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1470: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1480: 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61  g constant conta
1490: 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f 66 20  ins the text of 
14a0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
14b0: 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65  .** macro.  ^The
14c0: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
14d0: 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  ion() function r
14e0: 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
14f0: 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68   to the.** to th
1500: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
1510: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1520: 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ant.  The sqlite
1530: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a  3_libversion().*
1540: 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72  * function is pr
1550: 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65 20 69  ovided for use i
1560: 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c  n DLLs since DLL
1570: 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64   users usually d
1580: 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69  o not have.** di
1590: 72 65 63 74 20 61 63 63 65 73 73 20 74 6f 20 73  rect access to s
15a0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20  tring constants 
15b0: 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20  within the DLL. 
15c0: 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
15d0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
15e0: 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  er() function re
15f0: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
1600: 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51   equal to.** [SQ
1610: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1620: 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  BER].  ^The sqli
1630: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66  te3_sourceid() f
1640: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1650: 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
1660: 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61   a string consta
1670: 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69  nt whose value i
1680: 73 20 74 68 65 20 73 61 6d 65 20 61 73 20 74 68  s the same as th
1690: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  e .** [SQLITE_SO
16a0: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
16b0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a  ocessor macro..*
16c0: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
16d0: 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29  sqlite_version()
16e0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f  ] and [sqlite_so
16f0: 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53  urce_id()]..*/.S
1700: 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1710: 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74 20 63 68  _EXTERN const ch
1720: 61 72 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  ar sqlite3_versi
1730: 6f 6e 5b 5d 3b 0a 53 51 4c 49 54 45 5f 41 50 49  on[];.SQLITE_API
1740: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1750: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1760: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76  te3_libversion(v
1770: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1780: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1790: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
17a0: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
17b0: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
17c0: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
17d0: 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  L sqlite3_libver
17e0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64  sion_number(void
17f0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1800: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
1810: 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e  rary Compilation
1820: 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73   Options Diagnos
1830: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tics.**.** ^The 
1840: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1850: 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e  ption_used() fun
1860: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20  ction returns 0 
1870: 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74  or 1 .** indicat
1880: 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65 20  ing whether the 
1890: 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e  specified option
18a0: 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74 20   was defined at 
18b0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65  .** compile time
18c0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20  .  ^The SQLITE_ 
18d0: 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d  prefix may be om
18e0: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a  itted from the .
18f0: 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70  ** option name p
1900: 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33  assed to sqlite3
1910: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
1920: 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e  sed().  .**.** ^
1930: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  The sqlite3_comp
1940: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1950: 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  function allows 
1960: 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65  iterating.** ove
1970: 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70  r the list of op
1980: 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20  tions that were 
1990: 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69  defined at compi
19a0: 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65  le time by.** re
19b0: 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68  turning the N-th
19c0: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70   compile time op
19d0: 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49  tion string.  ^I
19e0: 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  f N is out of ra
19f0: 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  nge,.** sqlite3_
1a00: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1a10: 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55  t() returns a NU
1a20: 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68  LL pointer.  ^Th
1a30: 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72  e SQLITE_ .** pr
1a40: 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20  efix is omitted 
1a50: 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73  from any strings
1a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a   returned by .**
1a70: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a80: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a  option_get()..**
1a90: 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72  .** ^Support for
1aa0: 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20   the diagnostic 
1ab0: 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65  functions sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71  used().** and sq
1ae0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1af0: 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65  ion_get() may be
1b00: 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65 63   omitted by spec
1b10: 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b  ifying the .** [
1b20: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
1b30: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d  ILEOPTION_DIAGS]
1b40: 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69   option at compi
1b50: 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53  le time..**.** S
1b60: 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e  ee also: SQL fun
1b70: 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63  ctions [sqlite_c
1b80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1b90: 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  d()] and.** [sql
1ba0: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1bb0: 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65  n_get()] and the
1bc0: 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e   [compile_option
1bd0: 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69  s pragma]..*/.#i
1be0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
1bf0: 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f  T_COMPILEOPTION_
1c00: 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49  DIAGS.SQLITE_API
1c10: 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1c20: 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ALL sqlite3_comp
1c30: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63  ileoption_used(c
1c40: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e  onst char *zOptN
1c50: 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ame);.SQLITE_API
1c60: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c   const char *SQL
1c70: 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c80: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1c90: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1ca0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1cb0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1cc0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1cd0: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1ce0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1cf0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1d00: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1d10: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1d20: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1d30: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1d40: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1d50: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1d60: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1d70: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1d80: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1d90: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1da0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1db0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1dc0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1dd0: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1de0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1df0: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1e00: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1e10: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1e20: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1e30: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1e40: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1e50: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1e60: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1e70: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1e80: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1e90: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1ea0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1eb0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1ec0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1ed0: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1ee0: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1ef0: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1f00: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1f10: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1f20: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1f30: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1f40: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1f50: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1f60: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1f70: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1f80: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1f90: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1fa0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1fb0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1fc0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1fd0: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1fe0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1ff0: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2000: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
2010: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
2020: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
2030: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
2040: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
2050: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
2060: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
2070: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
2080: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
2090: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
20a0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
20b0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
20c0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
20d0: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
20e0: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
20f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2100: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2110: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2120: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2130: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2140: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2150: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2160: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
2170: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
2180: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
2190: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
21a0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
21b0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
21c0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
21d0: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
21e0: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
21f0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2200: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2210: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2220: 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20 5e  _SERIALIZED].  ^
2230: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
2240: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
2250: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
2260: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2270: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2280: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2290: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
22a0: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
22b0: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
22c0: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
22d0: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
22e0: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
22f0: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2300: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
2310: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2320: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
2330: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
2340: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2350: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
2360: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2370: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2380: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2390: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
23a0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
23b0: 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
23c0: 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
23d0: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
23e0: 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
23f0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 48 61 6e  e Connection Han
2400: 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  dle.** KEYWORDS:
2410: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2420: 63 74 69 6f 6e 7d 20 7b 64 61 74 61 62 61 73 65  ction} {database
2430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a   connections}.**
2440: 0a 2a 2a 20 45 61 63 68 20 6f 70 65 6e 20 53 51  .** Each open SQ
2450: 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 69 73  Lite database is
2460: 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20   represented by 
2470: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
2480: 69 6e 73 74 61 6e 63 65 20 6f 66 0a 2a 2a 20 74  instance of.** t
2490: 68 65 20 6f 70 61 71 75 65 20 73 74 72 75 63 74  he opaque struct
24a0: 75 72 65 20 6e 61 6d 65 64 20 22 73 71 6c 69 74  ure named "sqlit
24b0: 65 33 22 2e 20 20 49 74 20 69 73 20 75 73 65 66  e3".  It is usef
24c0: 75 6c 20 74 6f 20 74 68 69 6e 6b 20 6f 66 20 61  ul to think of a
24d0: 6e 20 73 71 6c 69 74 65 33 0a 2a 2a 20 70 6f 69  n sqlite3.** poi
24e0: 6e 74 65 72 20 61 73 20 61 6e 20 6f 62 6a 65 63  nter as an objec
24f0: 74 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  t.  The [sqlite3
2500: 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2510: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 61 6e  e3_open16()], an
2520: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d.** [sqlite3_op
2530: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
2540: 63 65 73 20 61 72 65 20 69 74 73 20 63 6f 6e 73  ces are its cons
2550: 74 72 75 63 74 6f 72 73 2c 20 61 6e 64 20 5b 73  tructors, and [s
2560: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 0a  qlite3_close()].
2570: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
2580: 63 6c 6f 73 65 5f 76 32 28 29 5d 20 61 72 65 20  close_v2()] are 
2590: 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 73 2e  its destructors.
25a0: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
25b0: 20 6f 74 68 65 72 0a 2a 2a 20 69 6e 74 65 72 66   other.** interf
25c0: 61 63 65 73 20 28 73 75 63 68 20 61 73 0a 2a 2a  aces (such as.**
25d0: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25e0: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
25f0: 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2600: 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  n()], and.** [sq
2610: 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
2620: 75 74 28 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75  ut()] to name bu
2630: 74 20 74 68 72 65 65 29 20 74 68 61 74 20 61 72  t three) that ar
2640: 65 20 6d 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a  e methods on an.
2650: 2a 2a 20 73 71 6c 69 74 65 33 20 6f 62 6a 65 63  ** sqlite3 objec
2660: 74 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  t..*/.typedef st
2670: 72 75 63 74 20 73 71 6c 69 74 65 33 20 73 71 6c  ruct sqlite3 sql
2680: 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ite3;../*.** CAP
2690: 49 33 52 45 46 3a 20 36 34 2d 42 69 74 20 49 6e  I3REF: 64-Bit In
26a0: 74 65 67 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b  teger Types.** K
26b0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f  EYWORDS: sqlite_
26c0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69 6e  int64 sqlite_uin
26d0: 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  t64.**.** Becaus
26e0: 65 20 74 68 65 72 65 20 69 73 20 6e 6f 20 63 72  e there is no cr
26f0: 6f 73 73 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79  oss-platform way
2700: 20 74 6f 20 73 70 65 63 69 66 79 20 36 34 2d 62   to specify 64-b
2710: 69 74 20 69 6e 74 65 67 65 72 20 74 79 70 65 73  it integer types
2720: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 63 6c 75  .** SQLite inclu
2730: 64 65 73 20 74 79 70 65 64 65 66 73 20 66 6f 72  des typedefs for
2740: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 61   64-bit signed a
2750: 6e 64 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  nd unsigned inte
2760: 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gers..**.** The 
2770: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e  sqlite3_int64 an
2780: 64 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  d sqlite3_uint64
2790: 20 61 72 65 20 74 68 65 20 70 72 65 66 65 72 72   are the preferr
27a0: 65 64 20 74 79 70 65 20 64 65 66 69 6e 69 74 69  ed type definiti
27b0: 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ons..** The sqli
27c0: 74 65 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  te_int64 and sql
27d0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
27e0: 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 66   are supported f
27f0: 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20  or backwards.** 
2800: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e  compatibility on
2810: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
2820: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64  qlite3_int64 and
2830: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 74 79   sqlite_int64 ty
2840: 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69 6e  pes can store in
2850: 74 65 67 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20  teger values.** 
2860: 62 65 74 77 65 65 6e 20 2d 39 32 32 33 33 37 32  between -9223372
2870: 30 33 36 38 35 34 37 37 35 38 30 38 20 61 6e 64  036854775808 and
2880: 20 2b 39 32 32 33 33 37 32 30 33 36 38 35 34 37   +92233720368547
2890: 37 35 38 30 37 20 69 6e 63 6c 75 73 69 76 65 2e  75807 inclusive.
28a0: 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
28b0: 33 5f 75 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  3_uint64 and sql
28c0: 69 74 65 5f 75 69 6e 74 36 34 20 74 79 70 65 73  ite_uint64 types
28d0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
28e0: 65 72 20 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65  er values .** be
28f0: 74 77 65 65 6e 20 30 20 61 6e 64 20 2b 31 38 34  tween 0 and +184
2900: 34 36 37 34 34 30 37 33 37 30 39 35 35 31 36 31  4674407370955161
2910: 35 20 69 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a  5 inclusive..*/.
2920: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  #ifdef SQLITE_IN
2930: 54 36 34 5f 54 59 50 45 0a 20 20 74 79 70 65 64  T64_TYPE.  typed
2940: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2950: 54 59 50 45 20 73 71 6c 69 74 65 5f 69 6e 74 36  TYPE sqlite_int6
2960: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2970: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
2980: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
2990: 69 6e 74 36 34 3b 0a 23 65 6c 69 66 20 64 65 66  int64;.#elif def
29a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
29b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
29c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
29d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
29e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
29f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
2a00: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2a10: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
2a20: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
2a30: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
2a40: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
2a50: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
2a60: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2a70: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
2a80: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
2a90: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
2aa0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
2ab0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
2ac0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
2ad0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
2ae0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
2af0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
2b00: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
2b10: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
2b20: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
2b30: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
2b40: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
2b50: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
2b60: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
2b70: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
2b80: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
2b90: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
2ba0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
2bb0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
2bc0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bd0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
2be0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2bf0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
2c00: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
2c10: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
2c20: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
2c30: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
2c40: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
2c50: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
2c60: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
2c70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2c80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2c90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ca0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2cb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2cc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2cd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2ce0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2cf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2d00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2d10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2d20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2d30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2d40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2d50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2d60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2d70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2d90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2da0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2db0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2dc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2dd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2de0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2df0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
2e00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2e10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2e20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2e30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2e40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2e50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2e60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2e70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2e80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2e90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ea0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2eb0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2ec0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2ed0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2ee0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2ef0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2f00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2f10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2f20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2f30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2f40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2f50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2f60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2f70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2f80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2f90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2fa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2fb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2fc0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2fd0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2fe0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ff0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
3000: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
3010: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
3020: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
3030: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
3040: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3050: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
3060: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
3070: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
3080: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
3090: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
30a0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
30b0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
30c0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
30d0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
30e0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
30f0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
3100: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
3110: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
3120: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
3130: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
3140: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
3150: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
3160: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
3170: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
3180: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
3190: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
31a0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
31b0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
31c0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
31d0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
31e0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
31f0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
3200: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
3210: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3220: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
3230: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
3240: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
3250: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
3260: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
3270: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
3280: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
3290: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
32a0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
32b0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
32c0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
32d0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
32e0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
32f0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
3300: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
3310: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
3320: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
3330: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
3340: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
3350: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
3360: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
3370: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
3380: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
3390: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
33a0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
33b0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
33c0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
33d0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
33e0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33f0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3400: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a 29  _close(sqlite3*)
3410: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
3420: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
3430: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3440: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3450: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3460: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
3470: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
3480: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
3490: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
34a0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
34b0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
34c0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
34d0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
34e0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
34f0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3500: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3510: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3520: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3530: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3540: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3550: 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
3560: 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e3.**.** The sql
3570: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3580: 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65  rface is a conve
3590: 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61  nience wrapper a
35a0: 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
35b0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
35c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
35d0: 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
35e0: 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20  finalize()],.** 
35f0: 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61  that allows an a
3600: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75  pplication to ru
3610: 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65  n multiple state
3620: 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20  ments of SQL.** 
3630: 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74  without having t
3640: 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43  o use a lot of C
3650: 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54   code. .**.** ^T
3660: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3670: 29 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73  ) interface runs
3680: 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54   zero or more UT
3690: 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20  F-8 encoded,.** 
36a0: 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
36b0: 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
36c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74  s passed into it
36d0: 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a  s 2nd argument,.
36e0: 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ** in the contex
36f0: 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
3700: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
3710: 61 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20  assed in as its 
3720: 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e  1st.** argument.
3730: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3740: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74  ck function of t
3750: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3760: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
3770: 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ec() is not NULL
3780: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76  , then it is inv
3790: 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65  oked for each re
37a0: 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69  sult row.** comi
37b0: 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76  ng out of the ev
37c0: 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74  aluated SQL stat
37d0: 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74  ements.  ^The 4t
37e0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  h argument to.**
37f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3800: 69 73 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75  is relayed throu
3810: 67 68 20 74 6f 20 74 68 65 20 31 73 74 20 61 72  gh to the 1st ar
3820: 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a  gument of each.*
3830: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63  * callback invoc
3840: 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20  ation.  ^If the 
3850: 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72  callback pointer
3860: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3870: 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  ().** is NULL, t
3880: 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20  hen no callback 
3890: 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20  is ever invoked 
38a0: 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20  and result rows 
38b0: 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a  are.** ignored..
38c0: 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72  **.** ^If an err
38d0: 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20  or occurs while 
38e0: 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53  evaluating the S
38f0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61  QL statements pa
3900: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  ssed into.** sql
3910: 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65  ite3_exec(), the
3920: 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74  n execution of t
3930: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
3940: 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a  ment stops and.*
3950: 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73 74 61  * subsequent sta
3960: 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70  tements are skip
3970: 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74  ped.  ^If the 5t
3980: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
3990: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
39a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
39b0: 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73  n any error mess
39c0: 61 67 65 20 69 73 20 77 72 69 74 74 65 6e 20 69  age is written i
39d0: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
39e0: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
39f0: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
3a00: 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b 20 74  nd passed back t
3a10: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
3a20: 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20  arameter..** To 
3a30: 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61  avoid memory lea
3a40: 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ks, the applicat
3a50: 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b  ion should invok
3a60: 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  e [sqlite3_free(
3a70: 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d  )].** on error m
3a80: 65 73 73 61 67 65 20 73 74 72 69 6e 67 73 20 72  essage strings r
3a90: 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20  eturned through 
3aa0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3ab0: 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r of.** sqlite3_
3ac0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3ad0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3ae0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3af0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3b00: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3b10: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3b20: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3b30: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3b40: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3b60: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3b70: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
3b80: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3b90: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3ba0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3bb0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3bc0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3bd0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3be0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3bf0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3c00: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3c10: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3c20: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3c30: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3c40: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3c50: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3c60: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3c70: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3c80: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3c90: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ca0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3cb0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3cc0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3cd0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3ce0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3cf0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3d00: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3d10: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3d20: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3d30: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3d40: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3d50: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3d60: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3d70: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3d80: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3d90: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3da0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3db0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3dc0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3dd0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3de0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3df0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3e00: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3e10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3e20: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3e30: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3e40: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3e50: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3e60: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3e70: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3e80: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3e90: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3ea0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3eb0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ec0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3ed0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3ee0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3ef0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3f00: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3f10: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3f20: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3f30: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3f40: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3f50: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3f60: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3f70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3f80: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3f90: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3fa0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3fb0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3fc0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3fd0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3fe0: 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72  ation must ensur
3ff0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
4000: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4010: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
4020: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
4030: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
4040: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
4050: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
4060: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
4070: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
4080: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
4090: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
40a0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
40b0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
40c0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
40d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
40e0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
40f0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
4100: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
4110: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
4120: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
4130: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
4140: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
4150: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4160: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
4170: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
4180: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c  .** </ul>.*/.SQL
4190: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
41a0: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
41b0: 65 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74  e3_exec(.  sqlit
41c0: 65 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20  e3*,            
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
41f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
4200: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20  onst char *sql, 
4210: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4220: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
4230: 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
4240: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c   */.  int (*call
4250: 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  back)(void*,int,
4260: 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20  char**,char**), 
4270: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e   /* Callback fun
4280: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
4290: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67        /* 1st arg
42c0: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63  ument to callbac
42d0: 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72  k */.  char **er
42e0: 72 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20  rmsg            
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
4310: 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
4320: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4330: 46 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  F: Result Codes.
4340: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
4350: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4360: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  tions}.**.** Man
4370: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
4380: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
4390: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
43a0: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
43b0: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
43c0: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
43d0: 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c   success or fail
43e0: 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65  ure..**.** New e
43f0: 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62  rror codes may b
4400: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
4410: 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
4420: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  Lite..**.** See 
4430: 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20  also: [extended 
4440: 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69  result code defi
4450: 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66  nitions].*/.#def
4460: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
4470: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4480: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4490: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
44a0: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
44b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
44c0: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
44d0: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
44e0: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
44f0: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4500: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4510: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
4520: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
4530: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
4540: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
4550: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
4560: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
4570: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4580: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4590: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
45a0: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
45b0: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
45c0: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
45d0: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
45e0: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
45f0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4600: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4610: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
4620: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
4630: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
4640: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
4650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4660: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
4670: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4680: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4690: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
46a0: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
46b0: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
46c0: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
46d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46e0: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
46f0: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4700: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4710: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
4720: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4730: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
4740: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
4750: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
4760: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
4770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4780: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4790: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
47a0: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
47b0: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
47c0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
47d0: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
47e0: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
47f0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4800: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4810: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
4820: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
4830: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
4840: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
4850: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
4860: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
4870: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4880: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4890: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
48a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
48b0: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
48c0: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
48d0: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
48e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
48f0: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4900: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4910: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
4920: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
4930: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
4940: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
4950: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
4960: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
4970: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4980: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4990: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
49a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
49c0: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
49d0: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
49e0: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4a00: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4a10: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
4a20: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
4a30: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
4a40: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
4a50: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
4a60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4a70: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4a80: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4a90: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4aa0: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4ab0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ac0: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4ad0: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4ae0: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4af0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4b00: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4b10: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
4b20: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
4b30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4b40: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
4b50: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
4b60: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
4b70: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4b80: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4b90: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4ba0: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4bb0: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4bc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4be0: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4bf0: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4c00: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4c10: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4c20: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4c30: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4c40: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4c50: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4c60: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4c70: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4c80: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4c90: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4ca0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4cb0: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4cc0: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4cd0: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4ce0: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4cf0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4d00: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4d10: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4d20: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4d30: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4d40: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4d50: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
4d60: 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65  .**.** In its de
4d70: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
4d80: 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20  ion, SQLite API 
4d90: 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
4da0: 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65  one of 30 intege
4db0: 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64  r.** [result cod
4dc0: 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65  es].  However, e
4dd0: 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68  xperience has sh
4de0: 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66  own that many of
4df0: 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74  .** these result
4e00: 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63   codes are too c
4e10: 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20  oarse-grained.  
4e20: 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76  They do not prov
4e30: 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69  ide as.** much i
4e40: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
4e50: 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f   problems as pro
4e60: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c  grammers might l
4e70: 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f  ike.  In an effo
4e80: 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73  rt to.** address
4e90: 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72   this, newer ver
4ea0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
4eb0: 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61  (version 3.3.8 a
4ec0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
4ed0: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
4ee0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
4ef0: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
4f00: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
4f10: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
4f20: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
4f30: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
4f50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4f60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4f70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4f80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4f90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4fa0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4fb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4fc0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
4fd0: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
4fe0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
4ff0: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
5000: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
5010: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
5020: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
5030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5040: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
5050: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5060: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
5070: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5080: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
5090: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
50a0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
50b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
50c0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
50d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
50e0: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5130: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5140: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
5150: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5160: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
5170: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
5180: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
5190: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
51a0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
51c0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51e0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
51f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
5200: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
5210: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5220: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
5230: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
5240: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
5250: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
5260: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5270: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
5280: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
5290: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
52a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
52c0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
52d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
52e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
52f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
5300: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5310: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
5320: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5330: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
5340: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
5350: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
5360: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5370: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
5380: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
5390: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
53a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
53c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
53d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
53e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
53f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
5400: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5410: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
5420: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5430: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
5440: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
5450: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
5460: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5470: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
5480: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
5490: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
54a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
54c0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
54d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
54e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
54f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
5500: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
5510: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
5520: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5530: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
5540: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
5550: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
5560: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5570: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
5580: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5590: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
55a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
55c0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
55d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
55e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
55f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
5600: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5610: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
5620: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5630: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
5640: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
5650: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
5660: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5670: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
5680: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
5690: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
56a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56b0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
56c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
56d0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
56e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
56f0: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
5700: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
5710: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5730: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
5740: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
5750: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
5780: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
5790: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
57a0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
57b0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
57c0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
57d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5800: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
5810: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5820: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5830: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5840: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
5850: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5860: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
5870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5880: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
5890: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
58a0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
58b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
58c0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
58d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
58e0: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
58f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5900: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
5910: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5920: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
5930: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5940: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
5950: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
5960: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
5970: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5980: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
5990: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
59a0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
59b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
59c0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
59d0: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
59e0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
59f0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
5a00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5a10: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
5a20: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
5a30: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
5a40: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
5a50: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
5a60: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
5a70: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
5ae0: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
5b20: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
5b60: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5be0: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
5bf0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5c00: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
5c30: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
5c40: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
5c50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5c60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
5c70: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
5c80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5c90: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
5ca0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5cb0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
5cc0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5cd0: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
5ce0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5cf0: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
5d00: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5d10: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
5d20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d30: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
5d40: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
5d50: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
5d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5d70: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
5d80: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
5d90: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
5da0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5db0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
5dc0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
5dd0: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
5de0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5df0: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
5e00: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5e10: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
5e20: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
5e30: 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20   Flags For File 
5e40: 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a  Open Operations.
5e50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20  **.** These bit 
5e60: 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e  values are inten
5e70: 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74  ded for use in t
5e80: 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65  he.** 3rd parame
5e90: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
5ea0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
5eb0: 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20  nterface and.** 
5ec0: 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  in the 4th param
5ed0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
5ee0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
5ef0: 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69  method..*/.#defi
5f00: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f10: 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20  EADONLY         
5f20: 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f  0x00000001  /* O
5f30: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f40: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5f50: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  ne SQLITE_OPEN_R
5f60: 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20  EADWRITE        
5f70: 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f  0x00000002  /* O
5f80: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5f90: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5fa0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ne SQLITE_OPEN_C
5fb0: 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20  REATE           
5fc0: 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f  0x00000004  /* O
5fd0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
5fe0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
5ff0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  ne SQLITE_OPEN_D
6000: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20  ELETEONCLOSE    
6010: 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56  0x00000008  /* V
6020: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6030: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  ne SQLITE_OPEN_E
6040: 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20  XCLUSIVE        
6050: 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56  0x00000010  /* V
6060: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6070: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41  ne SQLITE_OPEN_A
6080: 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20  UTOPROXY        
6090: 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56  0x00000020  /* V
60a0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
60b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  ne SQLITE_OPEN_U
60c0: 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RI              
60d0: 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f  0x00000040  /* O
60e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
60f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6100: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6110: 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20  EMORY           
6120: 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f  0x00000080  /* O
6130: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6140: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6150: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6160: 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20  AIN_DB          
6170: 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56  0x00000100  /* V
6180: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6190: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61a0: 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20  EMP_DB          
61b0: 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56  0x00000200  /* V
61c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
61d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
61e0: 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20  RANSIENT_DB     
61f0: 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56  0x00000400  /* V
6200: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6210: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
6220: 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  AIN_JOURNAL     
6230: 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56  0x00000800  /* V
6240: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6250: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54  ne SQLITE_OPEN_T
6260: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20  EMP_JOURNAL     
6270: 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56  0x00001000  /* V
6280: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6290: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
62a0: 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20  UBJOURNAL       
62b0: 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56  0x00002000  /* V
62c0: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
62d0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  ne SQLITE_OPEN_M
62e0: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20  ASTER_JOURNAL   
62f0: 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56  0x00004000  /* V
6300: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  FS only */.#defi
6310: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  ne SQLITE_OPEN_N
6320: 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20  OMUTEX          
6330: 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f  0x00008000  /* O
6340: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6350: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6360: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  ne SQLITE_OPEN_F
6370: 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20  ULLMUTEX        
6380: 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f  0x00010000  /* O
6390: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63a0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
63b0: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  ne SQLITE_OPEN_S
63c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
63d0: 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f  0x00020000  /* O
63e0: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
63f0: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6400: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  ne SQLITE_OPEN_P
6410: 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20  RIVATECACHE     
6420: 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f  0x00040000  /* O
6430: 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  k for sqlite3_op
6440: 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69  en_v2() */.#defi
6450: 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57  ne SQLITE_OPEN_W
6460: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AL              
6470: 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56  0x00080000  /* V
6480: 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52  FS only */../* R
6490: 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20  eserved:        
64a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
64b0: 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a   0x00F00000 */..
64c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
64d0: 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72  Device Character
64e0: 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65  istics.**.** The
64f0: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
6500: 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f  ristics method o
6510: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
6520: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62  o_methods].** ob
6530: 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ject returns an 
6540: 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
6550: 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65   a vector of the
6560: 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73  se.** bit values
6570: 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20   expressing I/O 
6580: 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  characteristics 
6590: 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72  of the mass stor
65a0: 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  age.** device th
65b0: 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c  at holds the fil
65c0: 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  e that the [sqli
65d0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
65e0: 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a  ** refers to..**
65f0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
6600: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
6610: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
6620: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
6630: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
6640: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6650: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
6660: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
6670: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
6680: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
6690: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
66a0: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
66b0: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
66c0: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
66d0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
66e0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
66f0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
6700: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
6710: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
6720: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
6730: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
6740: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
6750: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
6760: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
6770: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
6780: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
6790: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
67a0: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
67b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
67c0: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
67d0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
67e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
67f0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
6800: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
6810: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
6820: 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20   xWrite().  The 
6830: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57  SQLITE_IOCAP_POW
6840: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
6850: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6860: 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65  that.** after re
6870: 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  boot following a
6880: 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20   crash or power 
6890: 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62  loss, the only b
68a0: 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c  ytes in a.** fil
68b0: 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74  e that were writ
68c0: 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69  ten at the appli
68d0: 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67  cation level mig
68e0: 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a  ht have changed.
68f0: 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61  ** and that adja
6900: 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e  cent bytes, even
6910: 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68   bytes within th
6920: 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72  e same sector ar
6930: 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20  e.** guaranteed 
6940: 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e  to be unchanged.
6950: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6960: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
6970: 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67  HEN_OPEN.** flag
6980: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61   indicate that a
6990: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
69a0: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65  deleted when ope
69b0: 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54  n.  The.** SQLIT
69c0: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
69d0: 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73  E flag indicates
69e0: 20 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69   that the file i
69f0: 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c  s on.** read-onl
6a00: 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e  y media and cann
6a10: 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76  ot be changed ev
6a20: 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20  en by processes 
6a30: 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64  with.** elevated
6a40: 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a   privileges..*/.
6a50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a60: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
6a70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a80: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
6a90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6aa0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
6ab0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
6ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ad0: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
6ae0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6af0: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
6b00: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6b10: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
6b20: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
6b30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b40: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
6b50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6b60: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
6b70: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6b90: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
6ba0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6bb0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
6bc0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6c00: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
6c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6c20: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
6c30: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
6c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6c50: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
6c60: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6c70: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
6c80: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6c90: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
6ca0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
6cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6cc0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
6cd0: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
6ce0: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
6cf0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
6d00: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
6d10: 30 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69  0x00001000.#defi
6d20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6d30: 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20  IMMUTABLE       
6d40: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6d50: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6d60: 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20  F: File Locking 
6d70: 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  Levels.**.** SQL
6d80: 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20  ite uses one of 
6d90: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
6da0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
6db0: 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74  nd.** argument t
6dc0: 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73  o calls it makes
6dd0: 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20   to the xLock() 
6de0: 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65  and xUnlock() me
6df0: 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b  thods.** of an [
6e00: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6e10: 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  ds] object..*/.#
6e20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6e30: 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20  CK_NONE         
6e40: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
6e50: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20  E_LOCK_SHARED   
6e60: 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
6e70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
6e80: 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69  VED      2.#defi
6e90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  ne SQLITE_LOCK_P
6ea0: 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23  ENDING       3.#
6eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ec0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  CK_EXCLUSIVE    
6ed0: 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   4../*.** CAPI3R
6ee0: 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74  EF: Synchronizat
6ef0: 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a  ion Type Flags.*
6f00: 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65  *.** When SQLite
6f10: 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79   invokes the xSy
6f20: 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61  nc() method of a
6f30: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
6f40: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
6f50: 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69   it uses a combi
6f60: 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65  nation of.** the
6f70: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
6f80: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  s as the second 
6f90: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
6fa0: 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f  When the SQLITE_
6fb0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c  SYNC_DATAONLY fl
6fc0: 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d  ag is used, it m
6fd0: 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  eans that the.**
6fe0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20   sync operation 
6ff0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c  only needs to fl
7000: 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73  ush data to mass
7010: 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65   storage.  Inode
7020: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
7030: 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73  need not be flus
7040: 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65  hed. If the lowe
7050: 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74  r four bits of t
7060: 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c  he flag.** equal
7070: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7080: 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  MAL, that means 
7090: 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73  to use normal fs
70a0: 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e  ync() semantics.
70b0: 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72  .** If the lower
70c0: 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c   four bits equal
70d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
70e0: 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  L, that means.**
70f0: 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58   to use Mac OS X
7100: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20   style fullsync 
7110: 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63  instead of fsync
7120: 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74  ()..**.** Do not
7130: 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c   confuse the SQL
7140: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
7150: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
7160: 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69  FULL flags.** wi
7170: 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73  th the [PRAGMA s
7180: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d  ynchronous]=NORM
7190: 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73  AL and [PRAGMA s
71a0: 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c  ynchronous]=FULL
71b0: 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54  .** settings.  T
71c0: 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20  he [synchronous 
71d0: 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e  pragma] determin
71e0: 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f  es when calls to
71f0: 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46   the.** xSync VF
7200: 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61  S method occur a
7210: 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f  nd applies unifo
7220: 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20  rmly across all 
7230: 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68  platforms..** Th
7240: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7250: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
7260: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20  SYNC_FULL flags 
7270: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a  determine how.**
7280: 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69   energetic or ri
7290: 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66  gorous or forcef
72a0: 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72  ul the sync oper
72b0: 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a  ations are and.*
72c0: 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69  * only make a di
72d0: 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20  fference on Mac 
72e0: 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61  OSX for the defa
72f0: 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e  ult SQLite code.
7300: 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79  .** (Third-party
7310: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
7320: 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  ions might also 
7330: 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63  make the distinc
7340: 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20  tion.** between 
7350: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7360: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
7370: 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f  NC_FULL, but amo
7380: 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74  ng the.** operat
7390: 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69  ing systems nati
73a0: 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62  vely supported b
73b0: 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d  y SQLite, only M
73c0: 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20  ac OSX.** cares 
73d0: 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72  about the differ
73e0: 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e  ence.).*/.#defin
73f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
7400: 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30  RMAL        0x00
7410: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
7420: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20  TE_SYNC_FULL    
7430: 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64        0x00003.#d
7440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7450: 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20  C_DATAONLY      
7460: 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43  0x00010../*.** C
7470: 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65  API3REF: OS Inte
7480: 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20  rface Open File 
7490: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20  Handle.**.** An 
74a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
74b0: 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
74c0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e   an open file in
74d0: 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
74e0: 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72  3_vfs | OS inter
74f0: 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e  face layer].  In
7500: 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65  dividual OS inte
7510: 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  rface.** impleme
7520: 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a  ntations will.**
7530: 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73   want to subclas
7540: 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79  s this object by
7550: 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74   appending addit
7560: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20  ional fields.** 
7570: 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73  for their own us
7580: 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73  e.  The pMethods
7590: 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e   entry is a poin
75a0: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
75b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
75c0: 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
75d0: 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f  fines methods fo
75e0: 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20  r performing.** 
75f0: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f  I/O operations o
7600: 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e  n the open file.
7610: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
7620: 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ct sqlite3_file 
7630: 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74  sqlite3_file;.st
7640: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
7650: 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75  e {.  const stru
7660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7670: 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b  thods *pMethods;
7680: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72    /* Methods for
7690: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f   an open file */
76a0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
76b0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
76c0: 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d  e File Virtual M
76d0: 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a  ethods Object.**
76e0: 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f  .** Every file o
76f0: 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71  pened by the [sq
7700: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7710: 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65   method populate
7720: 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s an.** [sqlite3
7730: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f  _file] object (o
7740: 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79  r, more commonly
7750: 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  , a subclass of 
7760: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7770: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69  file] object) wi
7780: 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  th a pointer to 
7790: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
77a0: 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54  his object..** T
77b0: 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
77c0: 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75  es the methods u
77d0: 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  sed to perform v
77e0: 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e  arious operation
77f0: 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65  s.** against the
7800: 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65   open file repre
7810: 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73  sented by the [s
7820: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7830: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ect..**.** If th
7840: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7850: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74  Open] method set
7860: 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  s the sqlite3_fi
7870: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7880: 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e  ent .** to a non
7890: 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
78a0: 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
78b0: 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73  io_methods.xClos
78c0: 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20  e method.** may 
78d0: 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20  be invoked even 
78e0: 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  if the [sqlite3_
78f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72  vfs.xOpen] repor
7900: 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c  ted that it fail
7910: 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79  ed.  The.** only
7920: 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20   way to prevent 
7930: 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65  a call to xClose
7940: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
7950: 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  led [sqlite3_vfs
7960: 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f  .xOpen].** is fo
7970: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  r the [sqlite3_v
7980: 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74  fs.xOpen] to set
7990: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
79a0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
79b0: 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  nt.** to NULL..*
79c0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
79d0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63  rgument to xSync
79e0: 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b   may be one of [
79f0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
7a00: 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  AL] or.** [SQLIT
7a10: 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54  E_SYNC_FULL].  T
7a20: 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20  he first choice 
7a30: 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73  is the normal fs
7a40: 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65  ync()..** The se
7a50: 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61  cond choice is a
7a60: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
7a70: 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b  fullsync.  The [
7a80: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
7a90: 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61  ONLY].** flag ma
7aa0: 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20  y be ORed in to 
7ab0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e  indicate that on
7ac0: 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74  ly the data of t
7ad0: 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e  he file.** and n
7ae0: 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65  ot its inode nee
7af0: 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e  ds to be synced.
7b00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67  .**.** The integ
7b10: 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f  er values to xLo
7b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
7b30: 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a  () are one of.**
7b40: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7b50: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7b60: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
7b70: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
7b80: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7b90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a  LOCK_RESERVED],.
7ba0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7bb0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7bc0: 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
7bd0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7be0: 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78  ]..** </ul>.** x
7bf0: 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73  Lock() increases
7c00: 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f   the lock. xUnlo
7c10: 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74  ck() decreases t
7c20: 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20  he lock..** The 
7c30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7c40: 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63  ck() method chec
7c50: 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64  ks whether any d
7c60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7c70: 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e  on,.** either in
7c80: 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72   this process or
7c90: 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70   in some other p
7ca0: 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69  rocess, is holdi
7cb0: 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a  ng a RESERVED,.*
7cc0: 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58  * PENDING, or EX
7cd0: 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20  CLUSIVE lock on 
7ce0: 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65  the file.  It re
7cf0: 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66  turns true.** if
7d00: 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69   such a lock exi
7d10: 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74  sts and false ot
7d20: 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54  herwise..**.** T
7d30: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28  he xFileControl(
7d40: 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65  ) method is a ge
7d50: 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20  neric interface 
7d60: 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74  that allows cust
7d70: 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d  om.** VFS implem
7d80: 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72  entations to dir
7d90: 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e  ectly control an
7da0: 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67   open file using
7db0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
7dc0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7dd0: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
7de0: 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67   second "op" arg
7df0: 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69  ument is an.** i
7e00: 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20  nteger opcode.  
7e10: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
7e20: 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  nt is a generic 
7e30: 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64  pointer intended
7e40: 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20   to.** point to 
7e50: 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  a structure that
7e60: 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67   may contain arg
7e70: 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20  uments or space 
7e80: 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77  in which to.** w
7e90: 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75  rite return valu
7ea0: 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75  es.  Potential u
7eb0: 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e  ses for xFileCon
7ec0: 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a  trol() might be.
7ed0: 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20  ** functions to 
7ee0: 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20  enable blocking 
7ef0: 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f  locks with timeo
7f00: 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74  uts, to change t
7f10: 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74  he.** locking st
7f20: 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d  rategy (for exam
7f30: 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66  ple to use dot-f
7f40: 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69  ile locks), to i
7f50: 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20  nquire.** about 
7f60: 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20  the status of a 
7f70: 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61  lock, or to brea
7f80: 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20  k stale locks.  
7f90: 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f  The SQLite.** co
7fa0: 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20  re reserves all 
7fb0: 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61  opcodes less tha
7fc0: 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77  n 100 for its ow
7fd0: 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c  n use..** A [fil
7fe0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7ff0: 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f  s | list of opco
8000: 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31  des] less than 1
8010: 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  00 is available.
8020: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
8030: 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63   that define a c
8040: 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72  ustom xFileContr
8050: 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64  ol method should
8060: 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20   use opcodes.** 
8070: 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30  greater than 100
8080: 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69   to avoid confli
8090: 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d  cts.  VFS implem
80a0: 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
80b0: 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
80c0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72  TE_NOTFOUND] for
80d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70   file control op
80e0: 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20  codes that they 
80f0: 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e  do not.** recogn
8100: 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ize..**.** The x
8110: 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74  SectorSize() met
8120: 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20  hod returns the 
8130: 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74  sector size of t
8140: 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  he.** device tha
8150: 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20  t underlies the 
8160: 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f  file.  The secto
8170: 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a  r size is the.**
8180: 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74   minimum write t
8190: 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f  hat can be perfo
81a0: 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73  rmed without dis
81b0: 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72  turbing.** other
81c0: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
81d0: 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65  le.  The xDevice
81e0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28  Characteristics(
81f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
8200: 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72  rns a bit vector
8210: 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61   describing beha
8220: 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20  viors of the.** 
8230: 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63  underlying devic
8240: 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e:.**.** <ul>.**
8250: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8260: 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c  CAP_ATOMIC].** <
8270: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8280: 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20  P_ATOMIC512].** 
8290: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82a0: 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20  AP_ATOMIC1K].** 
82b0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82c0: 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20  AP_ATOMIC2K].** 
82d0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
82e0: 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20  AP_ATOMIC4K].** 
82f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8300: 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20  AP_ATOMIC8K].** 
8310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8320: 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a  AP_ATOMIC16K].**
8330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
8340: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a  CAP_ATOMIC32K].*
8350: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8360: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a  OCAP_ATOMIC64K].
8370: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8380: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
8390: 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  D].** <li> [SQLI
83a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
83b0: 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IAL].** </ul>.**
83c0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49  .** The SQLITE_I
83d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70  OCAP_ATOMIC prop
83e0: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20  erty means that 
83f0: 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a  all writes of.**
8400: 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74   any size are at
8410: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
8420: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e  E_IOCAP_ATOMICnn
8430: 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e  n values.** mean
8440: 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20   that writes of 
8450: 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20  blocks that are 
8460: 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  nnn bytes in siz
8470: 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69  e and.** are ali
8480: 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65  gned to an addre
8490: 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69  ss which is an i
84a0: 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  nteger multiple 
84b0: 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74  of.** nnn are at
84c0: 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54  omic.  The SQLIT
84d0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
84e0: 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a  END value means.
84f0: 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74  ** that when dat
8500: 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f  a is appended to
8510: 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74   a file, the dat
8520: 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a  a is appended.**
8530: 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20   first then the 
8540: 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65  size of the file
8550: 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65   is extended, ne
8560: 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  ver the other.**
8570: 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68   way around.  Th
8580: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8590: 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72  EQUENTIAL proper
85a0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
85b0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
85c0: 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20  written to disk 
85d0: 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65  in the same orde
85e0: 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  r as calls.** to
85f0: 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a   xWrite()..**.**
8600: 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75   If xRead() retu
8610: 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  rns SQLITE_IOERR
8620: 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d  _SHORT_READ it m
8630: 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a  ust also fill.**
8640: 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70   in the unread p
8650: 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62  ortions of the b
8660: 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73  uffer with zeros
8670: 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a  .  A VFS that.**
8680: 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66   fails to zero-f
8690: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
86a0: 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f  might seem to wo
86b0: 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  rk.  However,.**
86c0: 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f   failure to zero
86d0: 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64  -fill short read
86e0: 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c  s will eventuall
86f0: 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74  y lead to.** dat
8700: 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e  abase corruption
8710: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
8720: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
8730: 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69  ethods sqlite3_i
8740: 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63  o_methods;.struc
8750: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
8760: 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65  hods {.  int iVe
8770: 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78  rsion;.  int (*x
8780: 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66  Close)(sqlite3_f
8790: 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ile*);.  int (*x
87a0: 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69  Read)(sqlite3_fi
87b0: 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20  le*, void*, int 
87c0: 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e  iAmt, sqlite3_in
87d0: 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e  t64 iOfst);.  in
87e0: 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69  t (*xWrite)(sqli
87f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74  te3_file*, const
8800: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8810: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8820: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8830: 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74  xTruncate)(sqlit
8840: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8850: 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20  3_int64 size);. 
8860: 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71   int (*xSync)(sq
8870: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8880: 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28   flags);.  int (
8890: 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69  *xFileSize)(sqli
88a0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
88b0: 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29  e3_int64 *pSize)
88c0: 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29  ;.  int (*xLock)
88d0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
88e0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  int);.  int (*xU
88f0: 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  nlock)(sqlite3_f
8900: 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e  ile*, int);.  in
8910: 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76  t (*xCheckReserv
8920: 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  edLock)(sqlite3_
8930: 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73  file*, int *pRes
8940: 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
8950: 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69  ileControl)(sqli
8960: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
8970: 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a  p, void *pArg);.
8980: 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53    int (*xSectorS
8990: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
89a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65  e*);.  int (*xDe
89b0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
89c0: 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ics)(sqlite3_fil
89d0: 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  e*);.  /* Method
89e0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
89f0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20  d for version 1 
8a00: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d  */.  int (*xShmM
8a10: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
8a20: 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20  *, int iPg, int 
8a30: 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20  pgsz, int, void 
8a40: 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69  volatile**);.  i
8a50: 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73  nt (*xShmLock)(s
8a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8a70: 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c  t offset, int n,
8a80: 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76   int flags);.  v
8a90: 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65  oid (*xShmBarrie
8aa0: 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  r)(sqlite3_file*
8ab0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55  );.  int (*xShmU
8ac0: 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69  nmap)(sqlite3_fi
8ad0: 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46  le*, int deleteF
8ae0: 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  lag);.  /* Metho
8af0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8b00: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32  id for version 2
8b10: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74   */.  int (*xFet
8b20: 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ch)(sqlite3_file
8b30: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8b40: 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74   iOfst, int iAmt
8b50: 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20  , void **pp);.  
8b60: 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28  int (*xUnfetch)(
8b70: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8b80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8b90: 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20  st, void *p);.  
8ba0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8bb0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8bc0: 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a  ersion 3 */.  /*
8bd0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68   Additional meth
8be0: 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ods may be added
8bf0: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
8c00: 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  ses */.};../*.**
8c10: 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64   CAPI3REF: Stand
8c20: 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c  ard File Control
8c30: 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57   Opcodes.** KEYW
8c40: 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74  ORDS: {file cont
8c50: 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69  rol opcodes} {fi
8c60: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
8c70: 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  e}.**.** These i
8c80: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
8c90: 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72   are opcodes for
8ca0: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8cb0: 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74  l method.** of t
8cc0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8cd0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61  ethods] object a
8ce0: 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  nd for the [sqli
8cf0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8d00: 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
8d10: 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  ..**.** <ul>.** 
8d20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
8d30: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a  TL_LOCKSTATE]].*
8d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
8d50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
8d60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
8d70: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
8d80: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
8d90: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
8da0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
8db0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
8dc0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
8dd0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
8de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
8df0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
8e00: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
8e10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
8e20: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8e30: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
8e40: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
8e50: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
8e60: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
8e70: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
8e80: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
8e90: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
8ea0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
8eb0: 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79  ting and is only
8ec0: 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20   available when 
8ed0: 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  the SQLITE_TEST.
8ee0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
8ef0: 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
8f00: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8f10: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8f20: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
8f30: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8f40: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
8f50: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
8f60: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
8f70: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
8f80: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
8f90: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
8fa0: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
8fb0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
8fc0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
8fd0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
8fe0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
8ff0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
9000: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
9010: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
9020: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
9030: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
9040: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
9050: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
9060: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
9070: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
9080: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
9090: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
90a0: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
90b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
90c0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
90d0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
90e0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
90f0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
9100: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
9110: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
9120: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
9130: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
9140: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
9150: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
9160: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
9170: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
9180: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
9190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
91a0: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
91b0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
91c0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
91d0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
91e0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
91f0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
9200: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
9210: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
9220: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
9230: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
9240: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
9250: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
9260: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
9270: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
9280: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
9290: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
92a0: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
92b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
92c0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
92d0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
92e0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
92f0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
9300: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
9310: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
9320: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9330: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
9340: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
9350: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
9360: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
9370: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
9380: 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e  NTL_JOURNAL_POIN
9390: 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  TER]..**.** <li>
93a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a  [[SQLITE_FCNTL_J
93b0: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d  OURNAL_POINTER]]
93c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
93d0: 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f  FCNTL_JOURNAL_PO
93e0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
93f0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
9400: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
9410: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
9420: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
9430: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a 6f  ated with the jo
9440: 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74 68  urnal file (eith
9450: 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62  er.** the [rollb
9460: 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20  ack journal] or 
9470: 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61 64  the [write-ahead
9480: 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61 72   log]) for a par
9490: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
94a0: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
94b0: 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54   See also [SQLIT
94c0: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
94d0: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
94e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
94f0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9500: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
9510: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
9520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
9530: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9540: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9550: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9560: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9570: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9580: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9590: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
95a0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
95b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
95c0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
95d0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
95e0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
95f0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9600: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
9610: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
9620: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
9630: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9640: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9650: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9660: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9670: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9680: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9690: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
96a0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
96b0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
96c0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
96d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
96e0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
96f0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9700: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
9710: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
9720: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
9730: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9740: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9750: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9760: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9770: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9780: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9790: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
97a0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
97b0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
97c0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
97d0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
97e0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
97f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9800: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
9810: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
9820: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
9830: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9840: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9850: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9860: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9870: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9880: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9890: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
98a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
98b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
98c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
98d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
98e0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
98f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9900: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
9910: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
9920: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
9930: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9940: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9950: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9960: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9970: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9980: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9990: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
99a0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
99b0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
99c0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
99d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
99e0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
99f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9a00: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
9a10: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
9a20: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
9a30: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9a40: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9a60: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9a70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9a80: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9a90: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9aa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9ab0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9ac0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9ad0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9ae0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9af0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9b00: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
9b10: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
9b20: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
9b30: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9b40: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9b50: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9b60: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9b70: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9b80: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9b90: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9ba0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9bb0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9bc0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9bd0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9be0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9bf0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9c00: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
9c10: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
9c20: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
9c30: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9c40: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9c50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9c60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9c70: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9c80: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9c90: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9ca0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9cb0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9cc0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9cd0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9ce0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9cf0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9d00: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9d10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9d20: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9d30: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9d40: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9d50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9d60: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9d70: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9d80: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9d90: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9da0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9db0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9dc0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9dd0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9de0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9df0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9e00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9e10: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9e20: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9e30: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9e40: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9e50: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9e60: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9e70: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9e80: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9e90: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9ea0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9eb0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9ec0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9ed0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9ee0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9ef0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9f00: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9f10: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9f20: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9f30: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9f40: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9f50: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9f60: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9f70: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9f80: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9f90: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9fa0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9fb0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9fc0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9fd0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9fe0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9ff0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
a000: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
a010: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
a020: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
a030: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
a040: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
a050: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
a060: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
a070: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
a080: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
a090: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
a0a0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
a0b0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
a0c0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
a0d0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
a0e0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
a0f0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
a100: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
a110: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
a120: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
a130: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
a140: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
a150: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
a160: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
a170: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
a180: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a190: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
a1a0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
a1b0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
a1c0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
a1d0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
a1e0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
a1f0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
a200: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
a210: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
a220: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a230: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a240: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a250: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a260: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a270: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a280: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a290: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a2a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a2b0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a2c0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a2d0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a2e0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a2f0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a300: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a310: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a320: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a330: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a340: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a350: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a360: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a370: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a380: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a390: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a3a0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a3b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a3c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a3d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a3e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a3f0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a400: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a410: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a420: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a430: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a440: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a450: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a460: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a470: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a480: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a490: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a4a0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a4b0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a4c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a4d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a4e0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a4f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a500: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a510: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a520: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a530: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a540: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a550: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a560: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a570: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a580: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a590: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a5a0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a5b0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a5c0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a5d0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a5e0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a5f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a600: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a610: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a620: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a630: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a640: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a650: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a660: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a670: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a680: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a690: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a6a0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a6b0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a6c0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a6d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a6e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a6f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a700: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a710: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a720: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a730: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a740: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a750: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a760: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a770: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a780: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a790: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a7a0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a7b0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a7c0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a7d0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a7e0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a7f0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a800: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a810: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a820: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a830: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a840: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a850: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a860: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a870: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a880: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a890: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a8a0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a8b0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a8c0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a8d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
a8e0: 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e  S_POINTER]].** ^
a8f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
a900: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f  L_VFS_POINTER] o
a910: 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70 6f  pcode finds a po
a920: 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70  inter to the top
a930: 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73  -level.** [VFSes
a940: 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20 75  ] currently in u
a950: 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75 6d  se.  ^(The argum
a960: 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69  ent X in.** sqli
a970: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a980: 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c  (db,SQLITE_FCNTL
a990: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20  _VFS_POINTER,X) 
a9a0: 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79  must be.** of ty
a9b0: 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66 73  pe "[sqlite3_vfs
a9c0: 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70 63  ] **".  This opc
a9d0: 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a 58  odes will set *X
a9e0: 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65 72  .** to a pointer
a9f0: 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76 65   to the top-leve
aa00: 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65  l VFS.)^.** ^Whe
aa10: 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c 74  n there are mult
aa20: 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20 69  iple VFS shims i
aa30: 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68 69  n the stack, thi
aa40: 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 74  s opcode finds t
aa50: 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74  he.** upper-most
aa60: 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a   shim only..**.*
aa70: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aa80: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a  CNTL_PRAGMA]].**
aa90: 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52   ^Whenever a [PR
aaa0: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20  AGMA] statement 
aab0: 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53  is parsed, an [S
aac0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aad0: 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  MA] .** file con
aae0: 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20  trol is sent to 
aaf0: 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65  the open [sqlite
ab00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63  3_file] object c
ab10: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
ab20: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
ab30: 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68  file to which th
ab40: 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  e pragma stateme
ab50: 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20  nt refers. ^The 
ab60: 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
ab70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ab80: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ab90: 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61  ntrol is an arra
aba0: 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73  y of.** pointers
abb0: 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61   to strings (cha
abc0: 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68  r**) in which th
abd0: 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74  e second element
abe0: 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a   of the array.**
abf0: 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
ac00: 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74  the pragma and t
ac10: 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74  he third element
ac20: 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
ac30: 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d   to the.** pragm
ac40: 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65  a or NULL if the
ac50: 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61   pragma has no a
ac60: 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68  rgument.  ^The h
ac70: 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a  andler for an.**
ac80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ac90: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
aca0: 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c  rol can optional
acb0: 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73  ly make the firs
acc0: 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20  t element.** of 
acd0: 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d  the char** argum
ace0: 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ent point to a s
acf0: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
ad00: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
ad10: 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68  intf()].** or th
ad20: 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64  e equivalent and
ad30: 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c   that string wil
ad40: 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73  l become the res
ad50: 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ult of the pragm
ad60: 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f  a or.** the erro
ad70: 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65  r message if the
ad80: 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e   pragma fails. ^
ad90: 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
ada0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
adb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
adc0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  urns [SQLITE_NOT
add0: 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72  FOUND], then nor
ade0: 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d  mal .** [PRAGMA]
adf0: 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74   processing cont
ae00: 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20  inues.  ^If the 
ae10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ae20: 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f  AGMA].** file co
ae30: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ae40: 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20  QLITE_OK], then 
ae50: 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d  the parser assum
ae60: 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56  es that the.** V
ae70: 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74  FS has handled t
ae80: 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66  he PRAGMA itself
ae90: 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20   and the parser 
aea0: 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f  generates a no-o
aeb0: 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74  p.** prepared st
aec0: 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75 6c  atement if resul
aed0: 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c  t string is NULL
aee0: 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72 6e  , or that return
aef0: 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
af00: 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67  he result string
af10: 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   if the string i
af20: 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e  s non-NULL..** ^
af30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
af40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
af50: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
af60: 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20  s.** any result 
af70: 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20  code other than 
af80: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b  [SQLITE_OK] or [
af90: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
afa0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
afb0: 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63  that the VFS enc
afc0: 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f  ountered an erro
afd0: 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67  r while handling
afe0: 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e   the [PRAGMA] an
aff0: 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61  d the.** compila
b000: 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47  tion of the PRAG
b010: 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e  MA fails with an
b020: 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53   error.  ^The [S
b030: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
b040: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
b050: 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68  rol occurs at th
b060: 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70  e beginning of p
b070: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
b080: 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a  analysis and so.
b090: 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f  ** it is able to
b0a0: 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d   override built-
b0b0: 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74  in [PRAGMA] stat
b0c0: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ements..**.** <l
b0d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b0e0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a  _BUSYHANDLER]].*
b0f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
b100: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
b110: 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  ].** file-contro
b120: 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64  l may be invoked
b130: 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68   by SQLite on th
b140: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b150: 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c  handle.** shortl
b160: 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70  y after it is op
b170: 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ened in order to
b180: 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f   provide a custo
b190: 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73  m VFS with acces
b1a0: 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e  s.** to the conn
b1b0: 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e  ections busy-han
b1c0: 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54  dler callback. T
b1d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f  he argument is o
b1e0: 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29  f type (void **)
b1f0: 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f  .** - an array o
b200: 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76  f two (void *) v
b210: 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74  alues. The first
b220: 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c   (void *) actual
b230: 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20  ly points.** to 
b240: 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
b250: 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64  pe (int (*)(void
b260: 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74   *)). In order t
b270: 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e  o invoke the con
b280: 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79  nections.** busy
b290: 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66  -handler, this f
b2a0: 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62  unction should b
b2b0: 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
b2c0: 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20  he second (void 
b2d0: 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72  *) in.** the arr
b2e0: 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61  ay as the only a
b2f0: 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72  rgument. If it r
b300: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
b310: 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74   then the operat
b320: 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
b330: 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20   retried. If it 
b340: 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68  returns zero, th
b350: 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f  e custom VFS sho
b360: 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a  uld abandon the.
b370: 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61  ** current opera
b380: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
b390: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b3a0: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a  EMPFILENAME]].**
b3b0: 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61   ^Application ca
b3c0: 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51  n invoke the [SQ
b3d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
b3e0: 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f  ILENAME] file-co
b3f0: 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65  ntrol.** to have
b400: 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65   SQLite generate
b410: 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20   a.** temporary 
b420: 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74  filename using t
b430: 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68  he same algorith
b440: 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77  m that is follow
b450: 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a  ed to generate.*
b460: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
b470: 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74  names for TEMP t
b480: 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20  ables and other 
b490: 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20  internal uses.  
b4a0: 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  The.** argument 
b4b0: 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72  should be a char
b4c0: 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65  ** which will be
b4d0: 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
b4e0: 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69   filename.** wri
b4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
b500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
b510: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
b520: 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73  ].  The caller s
b530: 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20  hould.** invoke 
b540: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
b550: 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74   on the result t
b560: 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79  o avoid a memory
b570: 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   leak..**.** <li
b580: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b590: 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  MMAP_SIZE]].** T
b5a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b5b0: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
b5c0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
b5d0: 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74   to query or set
b5e0: 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20   the.** maximum 
b5f0: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
b600: 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65  that will be use
b610: 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70  d for memory-map
b620: 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20  ped I/O..** The 
b630: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
b640: 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65  inter to a value
b650: 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33   of type sqlite3
b660: 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69  _int64 that.** i
b670: 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61  s an advisory ma
b680: 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
b690: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
b6a0: 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e  e to memory map.
b6b0: 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72    The.** pointer
b6c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
b6d0: 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c  with the old val
b6e0: 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69  ue.  The limit i
b6f0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66  s not changed if
b700: 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72  .** the value or
b710: 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64  iginally pointed
b720: 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c   to is negative,
b730: 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72   and so the curr
b740: 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61  ent limit .** ca
b750: 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20  n be queried by 
b760: 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69  passing in a poi
b770: 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69  nter to a negati
b780: 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73  ve number.  This
b790: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
b7a0: 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
b7b0: 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  lly to implement
b7c0: 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69   [PRAGMA mmap_si
b7d0: 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ze]..**.** <li>[
b7e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b7f0: 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  ACE]].** The [SQ
b800: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
b810: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70  ] file control p
b820: 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79  rovides advisory
b830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
b840: 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74  to the VFS about
b850: 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72   what the higher
b860: 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53   layers of the S
b870: 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20  QLite stack are 
b880: 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66  doing..** This f
b890: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b8a0: 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20  sed by some VFS 
b8b0: 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67  activity tracing
b8c0: 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65   [shims]..** The
b8d0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a   argument is a z
b8e0: 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
b8f0: 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c  tring.  Higher l
b900: 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20  ayers in the.** 
b910: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79  SQLite stack may
b920: 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e   generate instan
b930: 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65  ces of this file
b940: 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74   control if.** t
b950: 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46  he [SQLITE_USE_F
b960: 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70  CNTL_TRACE] comp
b970: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
b980: 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  is enabled..**.*
b990: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b9a0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d  CNTL_HAS_MOVED]]
b9b0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b9c0: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
b9d0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e   file control in
b9e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
b9f0: 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f  ument as a.** po
ba00: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
ba10: 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65  ger and it write
ba20: 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f  s a boolean into
ba30: 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65   that integer de
ba40: 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68  pending.** on wh
ba50: 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
ba60: 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72   file has been r
ba70: 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f  enamed, moved, o
ba80: 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20  r deleted since 
ba90: 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20  it.** was first 
baa0: 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opened..**.** <l
bab0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bac0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
bad0: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
bae0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
baf0: 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64  ET_HANDLE] opcod
bb00: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
bb10: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
bb20: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
bb30: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
bb40: 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20   method to swap 
bb50: 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  the file handle 
bb60: 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20  with the one.** 
bb70: 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
bb80: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e  e pArg argument.
bb90: 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74    This capabilit
bba0: 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67  y is used during
bbb0: 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20   testing.** and 
bbc0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
bbd0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
bbe0: 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64  SQLITE_TEST is d
bbf0: 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  efined..**.** <l
bc00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bc10: 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20  _WAL_BLOCK]].** 
bc20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bc30: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20  L_WAL_BLOCK] is 
bc40: 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65 20  a signal to the 
bc50: 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20 69  VFS layer that i
bc60: 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61 64  t might.** be ad
bc70: 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62 6c  vantageous to bl
bc80: 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74 20  ock on the next 
bc90: 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65 20  WAL lock if the 
bca0: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65  lock is not imme
bcb0: 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c  diately.** avail
bcc0: 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20 73  able.  The WAL s
bcd0: 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73 20  ubsystem issues 
bce0: 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72 69  this signal duri
bcf0: 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63 75  ng rare.** circu
bd00: 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64 65  mstances in orde
bd10: 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62 6c  r to fix a probl
bd20: 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74 79  em with priority
bd30: 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41   inversion..** A
bd40: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
bd50: 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  ld <em>not</em> 
bd60: 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  use this file-co
bd70: 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ntrol..**.** <li
bd80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bd90: 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20  ZIPVFS]].** The 
bda0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49  [SQLITE_FCNTL_ZI
bdb0: 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73 20  PVFS] opcode is 
bdc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a  implemented by z
bdd0: 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20  ipvfs only. All 
bde0: 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f  other.** VFS sho
bdf0: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
be00: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74  E_NOTFOUND for t
be10: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a  his opcode..**.*
be20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
be30: 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68  CNTL_RBU]].** Th
be40: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
be50: 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  RBU] opcode is i
be60: 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74 68  mplemented by th
be70: 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75 73  e special VFS us
be80: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42 55  ed by.** the RBU
be90: 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e   extension only.
bea0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53 20    All other VFS 
beb0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bec0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bed0: 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64 65  r.** this opcode
bee0: 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .  .** </ul>.*/.
bef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bf00: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
bf10: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
bf20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bf30: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bf40: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
bf50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bf60: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
bf70: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
bf80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bf90: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
bfa0: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
bfb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bfc0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
bfd0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
bfe0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bff0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
c000: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
c010: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
c020: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
c030: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
c040: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
c050: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
c060: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
c070: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
c080: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
c090: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
c0a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
c0b0: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
c0c0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
c0d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
c0e0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
c0f0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
c100: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
c110: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
c120: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
c130: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c140: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
c150: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
c160: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
c170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
c180: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
c190: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
c1a0: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
c1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c1c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
c1d0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
c1e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c1f0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
c200: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
c210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c220: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
c230: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
c240: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c250: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
c260: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
c270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c280: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
c290: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
c2a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c2b0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
c2c0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
c2d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c2e0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
c2f0: 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e         23.#defin
c300: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
c310: 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20  AL_BLOCK        
c320: 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e 65        24.#define
c330: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49   SQLITE_FCNTL_ZI
c340: 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20 20  PVFS            
c350: 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65 20       25.#define 
c360: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20 53      26.#define S
c390: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f  QLITE_FCNTL_VFS_
c3a0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
c3b0: 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53 51     27.#define SQ
c3c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
c3d0: 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  AL_POINTER      
c3e0: 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72 65 63 61    28../* depreca
c3f0: 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65  ted names */.#de
c400: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
c410: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
c420: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c430: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c440: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c450: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
c460: 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46  LE      SQLITE_F
c470: 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_SET_LOCKPRO
c480: 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53  XYFILE.#define S
c490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
c4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c               SQL
c4b0: 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45  ITE_FCNTL_LAST_E
c4c0: 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  RRNO.../*.** CAP
c4d0: 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e  I3REF: Mutex Han
c4e0: 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75  dle.**.** The mu
c4f0: 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69  tex module withi
c500: 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73  n SQLite defines
c510: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
c520: 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73   to be an.** abs
c530: 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61  tract type for a
c540: 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20   mutex object.  
c550: 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
c560: 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61  never looks.** a
c570: 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  t the internal r
c580: 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66  epresentation of
c590: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74   an [sqlite3_mut
c5a0: 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a  ex].  It only.**
c5b0: 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e   deals with poin
c5c0: 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  ters to the [sql
c5d0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65  ite3_mutex] obje
c5e0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65  ct..**.** Mutexe
c5f0: 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
c600: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
c610: 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  ex_alloc()]..*/.
c620: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c630: 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c  qlite3_mutex sql
c640: 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a  ite3_mutex;../*.
c650: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
c660: 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74  Interface Object
c670: 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
c680: 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ce of the sqlite
c690: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66  3_vfs object def
c6a0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
c6b0: 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  ce between.** th
c6c0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e  e SQLite core an
c6d0: 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  d the underlying
c6e0: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
c6f0: 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a  m.  The "vfs".**
c700: 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   in the name of 
c710: 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64  the object stand
c720: 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66  s for "virtual f
c730: 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65  ile system".  Se
c740: 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20  e.** the [VFS | 
c750: 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  VFS documentatio
c760: 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69  n] for further i
c770: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
c780: 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * The value of t
c790: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
c7a0: 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31  d is initially 1
c7b0: 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67   but may be larg
c7c0: 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20  er in.** future 
c7d0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
c7e0: 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20  te.  Additional 
c7f0: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
c800: 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a  pended to this.*
c810: 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68  * object when th
c820: 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65  e iVersion value
c830: 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20   is increased.  
c840: 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74  Note that the st
c850: 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68  ructure.** of th
c860: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
c870: 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20  ject changes in 
c880: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
c890: 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74  between.** SQLit
c8a0: 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20  e version 3.5.9 
c8b0: 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65  and 3.6.0 and ye
c8c0: 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  t the iVersion f
c8d0: 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20  ield was not.** 
c8e0: 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20  modified..**.** 
c8f0: 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65  The szOsFile fie
c900: 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f  ld is the size o
c910: 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64  f the subclassed
c920: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a   [sqlite3_file].
c930: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65  ** structure use
c940: 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20  d by this VFS.  
c950: 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68  mxPathname is th
c960: 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
c970: 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d   of.** a pathnam
c980: 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a  e in this VFS..*
c990: 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20  *.** Registered 
c9a0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
c9b0: 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20  cts are kept on 
c9c0: 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f  a linked list fo
c9d0: 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70  rmed by.** the p
c9e0: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54  Next pointer.  T
c9f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
ca00: 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61  register()].** a
ca10: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  nd [sqlite3_vfs_
ca20: 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e  unregister()] in
ca30: 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20  terfaces manage 
ca40: 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20  this list.** in 
ca50: 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61  a thread-safe wa
ca60: 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  y.  The [sqlite3
ca70: 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74  _vfs_find()] int
ca80: 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68  erface.** search
ca90: 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65  es the list.  Ne
caa0: 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63  ither the applic
cab0: 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74  ation code nor t
cac0: 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d  he VFS.** implem
cad0: 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
cae0: 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f  use the pNext po
caf0: 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  inter..**.** The
cb00: 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20   pNext field is 
cb10: 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69  the only field i
cb20: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
cb30: 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74  s.** structure t
cb40: 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
cb50: 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51  ever modify.  SQ
cb60: 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61  Lite will only a
cb70: 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69  ccess.** or modi
cb80: 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68  fy this field wh
cb90: 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61  ile holding a pa
cba0: 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20  rticular static 
cbb0: 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70  mutex..** The ap
cbc0: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
cbd0: 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e   never modify an
cbe0: 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68  ything within th
cbf0: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a  e sqlite3_vfs.**
cc00: 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65   object once the
cc10: 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e   object has been
cc20: 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a   registered..**.
cc30: 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65  ** The zName fie
cc40: 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d  ld holds the nam
cc50: 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64  e of the VFS mod
cc60: 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d  ule.  The name m
cc70: 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65  ust.** be unique
cc80: 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20   across all VFS 
cc90: 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b  modules..**.** [
cca0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
ccb0: 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  en]].** ^SQLite 
ccc0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
ccd0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
cce0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
ccf0: 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20  .** is either a 
cd00: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20  NULL pointer or 
cd10: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a  string obtained.
cd20: 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74  ** from xFullPat
cd30: 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20  hname() with an 
cd40: 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20  optional suffix 
cd50: 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20  added..** ^If a 
cd60: 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20  suffix is added 
cd70: 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  to the zFilename
cd80: 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77   parameter, it w
cd90: 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f  ill.** consist o
cda0: 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63  f a single "-" c
cdb0: 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65  haracter followe
cdc0: 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61  d by no more tha
cdd0: 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d  n.** 11 alphanum
cde0: 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20  eric and/or "-" 
cdf0: 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e  characters..** ^
ce00: 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67  SQLite further g
ce10: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a  uarantees that.*
ce20: 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c  * the string wil
ce30: 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75  l be valid and u
ce40: 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78  nchanged until x
ce50: 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61  Close() is.** ca
ce60: 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66  lled. Because of
ce70: 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
ce80: 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b  ntence,.** the [
ce90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61  sqlite3_file] ca
cea0: 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61  n safely store a
ceb0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
cec0: 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69  ** filename if i
ced0: 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d  t needs to remem
cee0: 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ber the filename
cef0: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
cf00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c  ..** If the zFil
cf10: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
cf20: 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55  to xOpen is a NU
cf30: 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
cf40: 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e  xOpen.** must in
cf50: 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d  vent its own tem
cf60: 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20  porary name for 
cf70: 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e  the file.  ^When
cf80: 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69  ever the .** xFi
cf90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
cfa0: 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c   is NULL it will
cfb0: 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73   also be the cas
cfc0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c  e that the.** fl
cfd0: 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69  ags parameter wi
cfe0: 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49  ll include [SQLI
cff0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d000: 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  CLOSE]..**.** Th
d010: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d020: 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c   to xOpen() incl
d030: 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65  udes all bits se
d040: 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67  t in.** the flag
d050: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  s argument to [s
d060: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
d070: 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74  ].  Or if [sqlit
d080: 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72  e3_open()].** or
d090: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
d0a0: 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65  ()] is used, the
d0b0: 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73  n flags includes
d0c0: 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51   at least.** [SQ
d0d0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
d0e0: 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
d0f0: 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a  PEN_CREATE]. .**
d100: 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e   If xOpen() open
d110: 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e  s a file read-on
d120: 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20  ly then it sets 
d130: 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a  *pOutFlags to.**
d140: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
d150: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e  _OPEN_READONLY].
d160: 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20    Other bits in 
d170: 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62  *pOutFlags may b
d180: 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53  e set..**.** ^(S
d190: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20  QLite will also 
d1a0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d1b0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d1c0: 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a  o the xOpen().**
d1d0: 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67   call, depending
d1e0: 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62   on the object b
d1f0: 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a  eing opened:.**.
d200: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
d210: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d220: 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  IN_DB].** <li>  
d230: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
d240: 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  N_JOURNAL].** <l
d250: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d260: 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _TEMP_DB].** <li
d270: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d280: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  TEMP_JOURNAL].**
d290: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d2a0: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
d2b0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d2c0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
d2d0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d2e0: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
d2f0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
d300: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d310: 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  WAL].** </ul>)^.
d320: 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49  **.** The file I
d330: 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  /O implementatio
d340: 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62  n can use the ob
d350: 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20  ject type flags 
d360: 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  to.** change the
d370: 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69   way it deals wi
d380: 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65  th files.  For e
d390: 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
d3a0: 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64  cation.** that d
d3b0: 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f  oes not care abo
d3c0: 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72  ut crash recover
d3d0: 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69  y or rollback mi
d3e0: 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20  ght make.** the 
d3f0: 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61  open of a journa
d400: 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20  l file a no-op. 
d410: 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20   Writes to this 
d420: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a  journal would.**
d430: 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c   also be no-ops,
d440: 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74   and any attempt
d450: 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75   to read the jou
d460: 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72  rnal would retur
d470: 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52  n.** SQLITE_IOER
d480: 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65  R.  Or the imple
d490: 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20  mentation might 
d4a0: 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61  recognize that a
d4b0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d4c0: 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20  e will be doing 
d4d0: 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63  page-aligned sec
d4e0: 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72  tor reads and wr
d4f0: 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d  ites in a random
d500: 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65  .** order and se
d510: 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62  t up its I/O sub
d520: 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67  system according
d530: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ly..**.** SQLite
d540: 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20   might also add 
d550: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
d560: 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68  wing flags to th
d570: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a  e xOpen method:.
d580: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d590: 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  i> [SQLITE_OPEN_
d5a0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
d5b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d5c0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a  PEN_EXCLUSIVE].*
d5d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
d5e0: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
d5f0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c  ELETEONCLOSE] fl
d600: 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c  ag means the fil
d610: 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64  e should be.** d
d620: 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69  eleted when it i
d630: 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20  s closed.  ^The 
d640: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
d650: 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77  ETEONCLOSE].** w
d660: 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54  ill be set for T
d670: 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e  EMP databases an
d680: 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73  d their journals
d690: 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64  , transient.** d
d6a0: 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75  atabases, and su
d6b0: 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a  bjournals..**.**
d6c0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
d6d0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c  EN_EXCLUSIVE] fl
d6e0: 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  ag is always use
d6f0: 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e  d in conjunction
d700: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
d710: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d720: 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72  ] flag, which ar
d730: 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a  e both directly.
d740: 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20  ** analogous to 
d750: 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f  the O_EXCL and O
d760: 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20  _CREAT flags of 
d770: 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29  the POSIX open()
d780: 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51  .** API.  The SQ
d790: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d7a0: 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70  IVE flag, when p
d7b0: 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a  aired with the .
d7c0: 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  ** SQLITE_OPEN_C
d7d0: 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74  REATE, is used t
d7e0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
d7f0: 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61  file should alwa
d800: 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64  ys.** be created
d810: 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73  , and that it is
d820: 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20   an error if it 
d830: 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a  already exists..
d840: 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c  ** It is <i>not<
d850: 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69  /i> used to indi
d860: 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68  cate the file sh
d870: 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a  ould be opened .
d880: 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65  ** for exclusive
d890: 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e   access..**.** ^
d8a0: 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c  At least szOsFil
d8b0: 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  e bytes of memor
d8c0: 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20  y are allocated 
d8d0: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20  by SQLite.** to 
d8e0: 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74  hold the  [sqlit
d8f0: 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75  e3_file] structu
d900: 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  re passed as the
d910: 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65   third.** argume
d920: 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68  nt to xOpen.  Th
d930: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64  e xOpen method d
d940: 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a  oes not have to.
d950: 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20  ** allocate the 
d960: 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68  structure; it sh
d970: 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69  ould just fill i
d980: 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74  t in.  Note that
d990: 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65  .** the xOpen me
d9a0: 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68  thod must set th
d9b0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
d9c0: 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65  Methods to eithe
d9d0: 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71  r.** a valid [sq
d9e0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
d9f0: 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e  ] object or to N
da00: 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74  ULL.  xOpen must
da10: 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e   do.** this even
da20: 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69   if the open fai
da30: 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65  ls.  SQLite expe
da40: 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c  cts that the sql
da50: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
da60: 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69  ds.** element wi
da70: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65  ll be valid afte
da80: 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20  r xOpen returns 
da90: 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68  regardless of th
daa0: 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20  e success.** or 
dab0: 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78  failure of the x
dac0: 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a  Open call..**.**
dad0: 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78   [[sqlite3_vfs.x
dae0: 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65  Access]].** ^The
daf0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
db00: 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79  to xAccess() may
db10: 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   be [SQLITE_ACCE
db20: 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f  SS_EXISTS].** to
db30: 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78   test for the ex
db40: 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c  istence of a fil
db50: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
db60: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20  CESS_READWRITE] 
db70: 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68  to.** test wheth
db80: 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61  er a file is rea
db90: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
dba0: 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
dbb0: 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74  CCESS_READ].** t
dbc0: 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61  o test whether a
dbd0: 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73   file is at leas
dbe0: 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68  t readable.   Th
dbf0: 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a  e file can be a.
dc00: 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  ** directory..**
dc10: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
dc20: 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65   always allocate
dc30: 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68   at least mxPath
dc40: 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72  name+1 bytes for
dc50: 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62   the.** output b
dc60: 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e  uffer xFullPathn
dc70: 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20  ame.  The exact 
dc80: 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70  size of the outp
dc90: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
dca0: 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61  also passed as a
dcb0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f   parameter to bo
dcc0: 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20  th  methods. If 
dcd0: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
dce0: 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67  r.** is not larg
dcf0: 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54  e enough, [SQLIT
dd00: 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75  E_CANTOPEN] shou
dd10: 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
dd20: 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a  Since this is.**
dd30: 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61   handled as a fa
dd40: 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c  tal error by SQL
dd50: 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65  ite, vfs impleme
dd60: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ntations should 
dd70: 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70  endeavor.** to p
dd80: 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73  revent this by s
dd90: 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d  etting mxPathnam
dda0: 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e  e to a sufficien
ddb0: 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e  tly large value.
ddc0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  .**.** The xRand
ddd0: 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70  omness(), xSleep
dde0: 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65  (), xCurrentTime
ddf0: 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74  (), and xCurrent
de00: 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69  TimeInt64().** i
de10: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f  nterfaces are no
de20: 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72  t strictly a par
de30: 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73  t of the filesys
de40: 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72  tem, but they ar
de50: 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e  e.** included in
de60: 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75   the VFS structu
de70: 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e  re for completen
de80: 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ess..** The xRan
de90: 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69  domness() functi
dea0: 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  on attempts to r
deb0: 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74  eturn nBytes byt
dec0: 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75  es.** of good-qu
ded0: 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73  ality randomness
dee0: 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65   into zOut.  The
def0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73   return value is
df00: 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e  .** the actual n
df10: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f  umber of bytes o
df20: 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  f randomness obt
df30: 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53  ained..** The xS
df40: 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61  leep() method ca
df50: 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67  uses the calling
df60: 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70   thread to sleep
df70: 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74   for at.** least
df80: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d   the number of m
df90: 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65  icroseconds give
dfa0: 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e  n.  ^The xCurren
dfb0: 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f  tTime().** metho
dfc0: 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69  d returns a Juli
dfd0: 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f  an Day Number fo
dfe0: 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61  r the current da
dff0: 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a  te and time as.*
e000: 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  * a floating poi
e010: 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68  nt value..** ^Th
e020: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e030: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74  t64() method ret
e040: 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65  urns, as an inte
e050: 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a  ger, the Julian.
e060: 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75  ** Day Number mu
e070: 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30  ltiplied by 8640
e080: 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72  0000 (the number
e090: 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
e0a0: 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75   in .** a 24-hou
e0b0: 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51  r day).  .** ^SQ
e0c0: 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68  Lite will use th
e0d0: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  e xCurrentTimeIn
e0e0: 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20  t64() method to 
e0f0: 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a  get the current.
e100: 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  ** date and time
e110: 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20   if that method 
e120: 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66  is available (if
e130: 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f   iVersion is 2 o
e140: 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e  r .** greater an
e150: 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70  d the function p
e160: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
e170: 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c  LL) and will fal
e180: 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75  l back.** to xCu
e190: 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78  rrentTime() if x
e1a0: 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
e1b0: 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  () is unavailabl
e1c0: 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53  e..**.** ^The xS
e1d0: 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20  etSystemCall(), 
e1e0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  xGetSystemCall()
e1f0: 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65  , and xNestSyste
e200: 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  mCall() interfac
e210: 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73  es.** are not us
e220: 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65  ed by the SQLite
e230: 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70   core.  These op
e240: 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65  tional interface
e250: 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a  s are provided.*
e260: 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20  * by some VFSes 
e270: 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65  to facilitate te
e280: 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53  sting of the VFS
e290: 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69   code. By overri
e2a0: 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20  ding .** system 
e2b0: 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74  calls with funct
e2c0: 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63  ions under its c
e2d0: 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70  ontrol, a test p
e2e0: 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69  rogram can.** si
e2f0: 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e  mulate faults an
e300: 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f  d error conditio
e310: 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74  ns that would ot
e320: 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69  herwise be diffi
e330: 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73  cult.** or impos
e340: 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e  sible to induce.
e350: 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73    The set of sys
e360: 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63  tem calls that c
e370: 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e  an be overridden
e380: 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20  .** varies from 
e390: 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68  one VFS to anoth
e3a0: 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65  er, and from one
e3b0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
e3c0: 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a  same VFS to the.
e3d0: 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63  ** next.  Applic
e3e0: 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20  ations that use 
e3f0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
e400: 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65   must be prepare
e410: 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20  d for any.** or 
e420: 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74  all of these int
e430: 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55  erfaces to be NU
e440: 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20  LL or for their 
e450: 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e  behavior to chan
e460: 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72  ge.** from one r
e470: 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65  elease to the ne
e480: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
e490: 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d  s must not attem
e4a0: 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20  pt to access.** 
e4b0: 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74  any of these met
e4c0: 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72  hods if the iVer
e4d0: 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20  sion of the VFS 
e4e0: 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a  is less than 3..
e4f0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e500: 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71  t sqlite3_vfs sq
e510: 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64  lite3_vfs;.typed
e520: 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
e530: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76  3_syscall_ptr)(v
e540: 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c  oid);.struct sql
e550: 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74  ite3_vfs {.  int
e560: 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20   iVersion;      
e570: 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75        /* Structu
e580: 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  re version numbe
e590: 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20  r (currently 3) 
e5a0: 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c  */.  int szOsFil
e5b0: 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  e;            /*
e5c0: 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73   Size of subclas
e5d0: 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  sed sqlite3_file
e5e0: 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68   */.  int mxPath
e5f0: 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f  name;          /
e600: 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70  * Maximum file p
e610: 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a  athname length *
e620: 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20  /.  sqlite3_vfs 
e630: 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20  *pNext;      /* 
e640: 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20  Next registered 
e650: 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  VFS */.  const c
e660: 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20  har *zName;     
e670: 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69    /* Name of thi
e680: 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73  s virtual file s
e690: 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20  ystem */.  void 
e6a0: 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
e6b0: 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74      /* Pointer t
e6c0: 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70  o application-sp
e6d0: 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20  ecific data */. 
e6e0: 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71   int (*xOpen)(sq
e6f0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e700: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
e710: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20  qlite3_file*,.  
e720: 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74               int
e730: 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75   flags, int *pOu
e740: 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28  tFlags);.  int (
e750: 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65  *xDelete)(sqlite
e760: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e770: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73  ar *zName, int s
e780: 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28  yncDir);.  int (
e790: 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65  *xAccess)(sqlite
e7a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e7b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66  ar *zName, int f
e7c0: 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f  lags, int *pResO
e7d0: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75  ut);.  int (*xFu
e7e0: 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69  llPathname)(sqli
e7f0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e800: 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74  char *zName, int
e810: 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75   nOut, char *zOu
e820: 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44  t);.  void *(*xD
e830: 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  lOpen)(sqlite3_v
e840: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e850: 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76  *zFilename);.  v
e860: 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28  oid (*xDlError)(
e870: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
e880: 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a  t nByte, char *z
e890: 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20  ErrMsg);.  void 
e8a0: 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69  (*(*xDlSym)(sqli
e8b0: 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20  te3_vfs*,void*, 
e8c0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d  const char *zSym
e8d0: 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76  bol))(void);.  v
e8e0: 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28  oid (*xDlClose)(
e8f0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f  sqlite3_vfs*, vo
e900: 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  id*);.  int (*xR
e910: 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74  andomness)(sqlit
e920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e930: 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  te, char *zOut);
e940: 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29  .  int (*xSleep)
e950: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
e960: 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29  nt microseconds)
e970: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  ;.  int (*xCurre
e980: 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f  ntTime)(sqlite3_
e990: 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a  vfs*, double*);.
e9a0: 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74    int (*xGetLast
e9b0: 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
e9c0: 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a  fs*, int, char *
e9d0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
e9e0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
e9f0: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20  re in version 1 
ea00: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
ea10: 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65  s object.  ** de
ea20: 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65  finition.  Those
ea30: 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65   that follow are
ea40: 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f   added in versio
ea50: 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a  n 2 or later.  *
ea60: 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65  /.  int (*xCurre
ea70: 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c  ntTimeInt64)(sql
ea80: 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74  ite3_vfs*, sqlit
ea90: 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a  e3_int64*);.  /*
eaa0: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
eab0: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
eac0: 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20  ersions 1 and 2 
ead0: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
eae0: 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54  s object..  ** T
eaf0: 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66  hose below are f
eb00: 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64  or version 3 and
eb10: 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20   greater..  */. 
eb20: 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65   int (*xSetSyste
eb30: 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
eb40: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
eb50: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
eb60: 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20  syscall_ptr);.  
eb70: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
eb80: 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d  ptr (*xGetSystem
eb90: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
eba0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ebb0: 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20  zName);.  const 
ebc0: 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73  char *(*xNextSys
ebd0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ebe0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ebf0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a  r *zName);.  /*.
ec00: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ec10: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
ec20: 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68  rsions 1 through
ec30: 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   3 of the sqlite
ec40: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ec50: 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79  * New fields may
ec60: 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20   be appended in 
ec70: 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e  figure versions.
ec80: 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20    The iVersion. 
ec90: 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69   ** value will i
eca0: 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65  ncrement wheneve
ecb0: 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20  r this happens. 
ecc0: 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  .  */.};../*.** 
ecd0: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
ece0: 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20  for the xAccess 
ecf0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
ed00: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
ed10: 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20  onstants can be 
ed20: 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  used as the thir
ed30: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
ed40: 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  * the xAccess me
ed50: 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69  thod of an [sqli
ed60: 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
ed70: 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65    They determine
ed80: 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66  .** what kind of
ed90: 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65   permissions the
eda0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
edb0: 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a  is looking for..
edc0: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
edd0: 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68  CCESS_EXISTS, th
ede0: 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
edf0: 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b  .** simply check
ee00: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
ee10: 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69  le exists..** Wi
ee20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
ee30: 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20  _READWRITE, the 
ee40: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
ee50: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
ee60: 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63   the named direc
ee70: 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61  tory is both rea
ee80: 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62  dable and writab
ee90: 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20  le.** (in other 
eea0: 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20  words, if files 
eeb0: 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65  can be added, re
eec0: 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d  moved, and renam
eed0: 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  ed within.** the
eee0: 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20   directory)..** 
eef0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
ef00: 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73  S_READWRITE cons
ef10: 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c  tant is currentl
ef20: 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74  y used only by t
ef30: 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72  he.** [temp_stor
ef40: 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
ef50: 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73  ma], though this
ef60: 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e   could change in
ef70: 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c   a future.** rel
ef80: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
ef90: 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41  ** With SQLITE_A
efa0: 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20  CCESS_READ, the 
efb0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a  xAccess method.*
efc0: 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  * checks whether
efd0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61   the file is rea
efe0: 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49  dable.  The SQLI
eff0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63  TE_ACCESS_READ c
f000: 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75  onstant is.** cu
f010: 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20  rrently unused, 
f020: 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20  though it might 
f030: 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74  be used in a fut
f040: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
f050: 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  * SQLite..*/.#de
f060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f070: 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23  SS_EXISTS    0.#
f080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43  define SQLITE_AC
f090: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31  CESS_READWRITE 1
f0a0: 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52     /* Used by PR
f0b0: 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f  AGMA temp_store_
f0c0: 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65  directory */.#de
f0d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45  fine SQLITE_ACCE
f0e0: 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20  SS_READ      2  
f0f0: 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f   /* Unused */../
f100: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
f110: 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68  lags for the xSh
f120: 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64  mLock VFS method
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f140: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64  eger constants d
f150: 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75  efine the variou
f160: 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74  s locking operat
f170: 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20  ions.** allowed 
f180: 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  by the xShmLock 
f190: 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74  method of [sqlit
f1a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20  e3_io_methods]. 
f1b0: 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e   The.** followin
f1c0: 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c  g are the only l
f1d0: 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  egal combination
f1e0: 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68  s of flags to th
f1f0: 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65  e.** xShmLock me
f200: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
f210: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f220: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
f230: 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
f240: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f250: 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
f260: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
f270: 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
f280: 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
f290: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
f2a0: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
f2b0: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
f2c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
f2d0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68  * </ul>.**.** Wh
f2e0: 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68  en unlocking, th
f2f0: 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72  e same SHARED or
f300: 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20   EXCLUSIVE flag 
f310: 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64  must be supplied
f320: 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e   as.** was given
f330: 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f   on the correspo
f340: 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a  nding lock.  .**
f350: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f360: 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e   method can tran
f370: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75  sition between u
f380: 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52  nlocked and SHAR
f390: 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e  ED or.** between
f3a0: 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58   unlocked and EX
f3b0: 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e  CLUSIVE.  It can
f3c0: 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  not transition b
f3d0: 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a  etween SHARED.**
f3e0: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a   and EXCLUSIVE..
f3f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f400: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20  E_SHM_UNLOCK    
f410: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
f420: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20  ITE_SHM_LOCK    
f430: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
f440: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f450: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
f460: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
f470: 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a  USIVE    8../*.*
f480: 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69  * CAPI3REF: Maxi
f490: 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64  mum xShmLock ind
f4a0: 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68  ex.**.** The xSh
f4b0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20  mLock method on 
f4c0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f4d0: 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c  ods] may use val
f4e0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  ues.** between 0
f4f0: 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20   and this upper 
f500: 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66  bound as its "of
f510: 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a  fset" argument..
f520: 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
f530: 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74  re will never at
f540: 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65  tempt to acquire
f550: 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a   or release a.**
f560: 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66   lock outside of
f570: 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23   this range.*/.#
f580: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f590: 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38  M_NLOCK        8
f5a0: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
f5b0: 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68  F: Initialize Th
f5c0: 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
f5d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f5e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f5f0: 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c   routine initial
f600: 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69  izes the.** SQLi
f610: 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68  te library.  ^Th
f620: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f630: 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  wn() routine.** 
f640: 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20  deallocates any 
f650: 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77  resources that w
f660: 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ere allocated by
f670: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f680: 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20  ize()..** These 
f690: 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73  routines are des
f6a0: 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20  igned to aid in 
f6b0: 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
f6c0: 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68  zation and.** sh
f6d0: 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64  utdown on embedd
f6e0: 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72  ed systems.  Wor
f6f0: 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61  kstation applica
f700: 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53  tions using.** S
f710: 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64  QLite normally d
f720: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e  o not need to in
f730: 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74  voke either of t
f740: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
f750: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f760: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f770: 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63  e() is an "effec
f780: 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74  tive" call if it
f790: 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   is.** the first
f7a0: 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e   time sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e  itialize() is in
f7c0: 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65  voked during the
f7d0: 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20   lifetime of.** 
f7e0: 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20  the process, or 
f7f0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
f800: 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f  st time sqlite3_
f810: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
f820: 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  invoked.** follo
f830: 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73  wing a call to s
f840: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f850: 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66  ).  ^(Only an ef
f860: 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20  fective call.** 
f870: 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  of sqlite3_initi
f880: 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79  alize() does any
f890: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e   initialization.
f8a0: 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c    All other call
f8b0: 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73  s.** are harmles
f8c0: 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a  s no-ops.)^.**.*
f8d0: 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
f8e0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
f8f0: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f900: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74   call if it is t
f910: 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c  he first.** call
f920: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
f930: 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65  down() since the
f940: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e   last sqlite3_in
f950: 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f  itialize().  ^(O
f960: 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74  nly.** an effect
f970: 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ive call to sqli
f980: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64  te3_shutdown() d
f990: 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61  oes any deinitia
f9a0: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c  lization..** All
f9b0: 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c   other valid cal
f9c0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ls to sqlite3_sh
f9d0: 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72  utdown() are har
f9e0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f9f0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fa00: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
fa10: 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65  nterface is thre
fa20: 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69  adsafe, but sqli
fa30: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a  te3_shutdown().*
fa40: 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73  * is not.  The s
fa50: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
fa60: 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74  ) interface must
fa70: 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
fa80: 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65  from a.** single
fa90: 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70   thread.  All op
faa0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
fab0: 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62  nections] must b
fac0: 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c  e closed and all
fad0: 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65  .** other SQLite
fae0: 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20   resources must 
faf0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70  be deallocated p
fb00: 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67  rior to invoking
fb10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74  .** sqlite3_shut
fb20: 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d  down()..**.** Am
fb30: 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73  ong other things
fb40: 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  , ^sqlite3_initi
fb50: 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76  alize() will inv
fb60: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  oke.** sqlite3_o
fb70: 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c  s_init().  Simil
fb80: 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73  arly, ^sqlite3_s
fb90: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c  hutdown().** wil
fba0: 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  l invoke sqlite3
fbb0: 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a  _os_end()..**.**
fbc0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
fbd0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
fbe0: 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ne returns [SQLI
fbf0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
fc00: 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f  s..** ^If for so
fc10: 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74  me reason, sqlit
fc20: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
fc30: 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69  is unable to ini
fc40: 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c  tialize.** the l
fc50: 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20  ibrary (perhaps 
fc60: 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  it is unable to 
fc70: 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65  allocate a neede
fc80: 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a  d resource such.
fc90: 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69  ** as a mutex) i
fca0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72  t returns an [er
fcb0: 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20  ror code] other 
fcc0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
fcd0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
fce0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fcf0: 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
fd00: 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  led internally b
fd10: 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  y many other.** 
fd20: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
fd30: 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70  s so that an app
fd40: 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79  lication usually
fd50: 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
fd60: 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69  o.** invoke sqli
fd70: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd80: 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20   directly.  For 
fd90: 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65  example, [sqlite
fda0: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c  3_open()].** cal
fdb0: 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ls sqlite3_initi
fdc0: 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53  alize() so the S
fdd0: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
fde0: 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
fdf0: 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  lly.** initializ
fe00: 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
fe10: 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c  _open()] is call
fe20: 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74  ed if it has not
fe30: 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a   be initialized.
fe40: 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f  ** already.  ^Ho
fe50: 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65  wever, if SQLite
fe60: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
fe70: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d  h the [SQLITE_OM
fe80: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20  IT_AUTOINIT].** 
fe90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
fea0: 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75  ion, then the au
feb0: 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f  tomatic calls to
fec0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fed0: 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69  ize().** are omi
fee0: 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70  tted and the app
fef0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61  lication must ca
ff00: 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ll sqlite3_initi
ff10: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
ff20: 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69  .** prior to usi
ff30: 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c  ng any other SQL
ff40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
ff50: 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74  For maximum port
ff60: 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69  ability,.** it i
ff70: 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
ff80: 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  at applications 
ff90: 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71  always invoke sq
ffa0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ffb0: 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70  ().** directly p
ffc0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
ffd0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
ffe0: 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72  nterface.  Futur
fff0: 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66  e releases.** of
10000 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75   SQLite may requ
10010 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74  ire this.  In ot
10020 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62  her words, the b
10030 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65  ehavior exhibite
10040 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  d.** when SQLite
10050 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10060 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  h [SQLITE_OMIT_A
10070 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62  UTOINIT] might b
10080 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66  ecome the.** def
10090 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e  ault behavior in
100a0 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c   some future rel
100b0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ease of SQLite..
100c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
100d0 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74  3_os_init() rout
100e0 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69  ine does operati
100f0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
10100 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61  ic.** initializa
10110 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69  tion of the SQLi
10120 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65  te library.  The
10130 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10140 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64  ).** routine und
10150 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f  oes the effect o
10160 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  f sqlite3_os_ini
10170 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61  t().  Typical ta
10180 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  sks.** performed
10190 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e   by these routin
101a0 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63  es include alloc
101b0 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  ation or dealloc
101c0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74  ation.** of stat
101d0 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e  ic resources, in
101e0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
101f0 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
10200 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20  ,.** setting up 
10210 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  a default [sqlit
10220 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20  e3_vfs] module, 
10230 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a  or setting up.**
10240 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69   a default confi
10250 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b  guration using [
10260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10270 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  ]..**.** The app
10280 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
10290 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74  never invoke eit
102a0 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  her sqlite3_os_i
102b0 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  nit().** or sqli
102c0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72  te3_os_end() dir
102d0 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c  ectly.  The appl
102e0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f  ication should o
102f0 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  nly invoke.** sq
10300 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10310 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73  () and sqlite3_s
10320 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20  hutdown().  The 
10330 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10340 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
10350 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74  s called automat
10360 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65  ically by sqlite
10370 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61  3_initialize() a
10380 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  nd.** sqlite3_os
10390 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64  _end() is called
103a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74   by sqlite3_shut
103b0 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72  down().  Appropr
103c0 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  iate.** implemen
103d0 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69  tations for sqli
103e0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e  te3_os_init() an
103f0 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  d sqlite3_os_end
10400 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20  ().** are built 
10410 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e  into SQLite when
10420 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20   it is compiled 
10430 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77  for Unix, Window
10440 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57  s, or OS/2..** W
10450 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c  hen [custom buil
10460 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f  ds | built for o
10470 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a  ther platforms].
10480 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53  ** (using the [S
10490 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31  QLITE_OS_OTHER=1
104a0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
104b0 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70  * option) the ap
104c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73  plication must s
104d0 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65  upply a suitable
104e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
104f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
10500 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
10510 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20  ite3_os_end().  
10520 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  An application-s
10530 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65  upplied.** imple
10540 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c  mentation of sql
10550 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f  ite3_os_init() o
10560 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10570 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72  ().** must retur
10580 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
10590 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d   success and som
105a0 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63  e other [error c
105b0 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69  ode] upon.** fai
105c0 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lure..*/.SQLITE_
105d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
105e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 69  TDCALL sqlite3_i
105f0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
10600 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
10610 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
10620 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10630 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
10640 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
10650 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f  CALL sqlite3_os_
10660 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
10670 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
10680 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
10690 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a  3_os_end(void);.
106a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
106b0 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65   Configuring The
106c0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
106d0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
106e0 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
106f0 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
10700 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66  make global conf
10710 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
10720 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69  nges to SQLite i
10730 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20  n order to tune 
10740 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70  SQLite to the sp
10750 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a  ecific needs of.
10760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
10770 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  on.  The default
10780 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69   configuration i
10790 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  s recommended fo
107a0 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63  r most.** applic
107b0 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68  ations and so th
107c0 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73  is routine is us
107d0 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73  ually not necess
107e0 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70  ary.  It is.** p
107f0 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f  rovided to suppo
10800 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61 74  rt rare applicat
10810 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61  ions with unusua
10820 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c  l needs..**.** <
10830 62 3e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  b>The sqlite3_co
10840 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10850 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10860 66 65 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74  fe. The applicat
10870 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
10880 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
10890 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
108a0 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
108b0 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
108c0 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
108d0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
108e0 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20  ning.</b>.**.** 
108f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10900 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a  ig() interface.*
10910 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
10920 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
10930 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
10940 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
10950 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10960 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
10970 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
10980 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
10990 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
109a0 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
109b0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
109c0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
109d0 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
109e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
109f0 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
10a00 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
10a10 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
10a20 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
10a30 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
10a40 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
10a50 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
10a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10a70 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
10a80 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
10a90 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
10aa0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
10ab0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
10ac0 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
10ad0 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
10ae0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10af0 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
10b00 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
10b10 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
10b20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
10b30 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
10b40 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
10b50 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
10b60 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
10b70 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
10b80 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10b90 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
10ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10bb0 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
10bc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
10bd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
10be0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
10bf0 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
10c00 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
10c10 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
10c20 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
10c30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
10c40 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
10c50 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
10c60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
10c70 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74  LITE_CDECL sqlit
10c80 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e  e3_config(int, .
10c90 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
10ca0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20  3REF: Configure 
10cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10cc0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
10cd0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
10ce0 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10cf0 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10d00 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10d10 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10d20 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10d30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10d40 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
10d50 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar 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 65 78 63 65 70 74 20 74  nfig()] except t
10d80 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
10d90 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10da0 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10db0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
10dc0 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
10dd0 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
10de0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10df0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10e00 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
10e10 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10e20 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
10e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10e50 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
10e60 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
10e70 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
10e80 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
10e90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10ea0 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10eb0 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
10ec0 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
10ed0 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10ee0 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10ef0 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
10f00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
10f10 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10f20 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10f30 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
10f40 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
10f50 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
10f60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
10f70 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 20  nt SQLITE_CDECL 
10f80 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
10f90 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  g(sqlite3*, int 
10fa0 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  op, ...);../*.**
10fb0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
10fc0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75  y Allocation Rou
10fd0 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  tines.**.** An i
10fe0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
10ff0 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
11000 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
11010 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  ween SQLite.** a
11020 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  nd low-level mem
11030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
11040 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
11050 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73  his object is us
11060 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70  ed in only one p
11070 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69  lace in the SQLi
11080 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
11090 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   A pointer to an
110a0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
110b0 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20  s object is the 
110c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b  argument to.** [
110d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
110e0 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69  ] when the confi
110f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
11100 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  is.** [SQLITE_CO
11110 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20  NFIG_MALLOC] or 
11120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
11130 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20  ETMALLOC].  .** 
11140 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69  By creating an i
11150 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
11160 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61  object.** and pa
11170 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
11180 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
11190 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
111a0 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63  OC]).** during c
111b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e  onfiguration, an
111c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
111d0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
111e0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
111f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
11200 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74  system for SQLit
11210 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c  e to use for all
11220 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d   of its.** dynam
11230 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e  ic memory needs.
11240 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
11250 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69   SQLite comes wi
11260 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c  th several [buil
11270 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
11280 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20  cators].** that 
11290 61 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64  are perfectly ad
112a0 65 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f  equate for the o
112b0 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f  verwhelming majo
112c0 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
112d0 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74  ions.** and that
112e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
112f0 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61  only useful to a
11300 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f   tiny minority o
11310 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
11320 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a  * with specializ
11330 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
11340 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74  tion requirement
11350 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  s.  This object 
11360 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20  is.** also used 
11370 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f  during testing o
11380 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65  f SQLite in orde
11390 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20  r to specify an 
113a0 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
113b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
113c0 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d  that simulates m
113d0 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d  emory out-of-mem
113e0 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69  ory conditions i
113f0 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65  n.** order to ve
11400 72 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65  rify that SQLite
11410 20 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66   recovers gracef
11420 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a  ully from such.*
11430 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a  * conditions..**
11440 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c  .** The xMalloc,
11450 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78   xRealloc, and x
11460 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73  Free methods mus
11470 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a  t work like the.
11480 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61  ** malloc(), rea
11490 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
114a0 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
114b0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
114c0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c  library..** ^SQL
114d0 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
114e0 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61  hat the second a
114f0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52  rgument to.** xR
11500 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73  ealloc is always
11510 20 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65   a value returne
11520 64 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c  d by a prior cal
11530 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a  l to xRoundup..*
11540 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c  *.** xSize shoul
11550 64 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c  d return the all
11560 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61  ocated size of a
11570 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11580 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  on.** previously
11590 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78   obtained from x
115a0 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c  Malloc or xReall
115b0 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74  oc.  The allocat
115c0 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c  ed size.** is al
115d0 77 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73  ways at least as
115e0 20 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75   big as the requ
115f0 65 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d  ested size but m
11600 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a  ay be larger..**
11610 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70  .** The xRoundup
11620 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
11630 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68  what would be th
11640 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
11650 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20   of.** a memory 
11660 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e  allocation given
11670 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65   a particular re
11680 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d  quested size.  M
11690 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ost memory.** al
116a0 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
116b0 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  p memory allocat
116c0 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f  ions at least to
116d0 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70   the next multip
116e0 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d  le.** of 8.  Som
116f0 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  e allocators rou
11700 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65  nd up to a large
11710 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f  r multiple or to
11720 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a   a power of 2..*
11730 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61  * Every memory a
11740 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73  llocation reques
11750 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f  t coming in thro
11760 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ugh [sqlite3_mal
11770 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71  loc()].** or [sq
11780 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
11790 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f   first calls xRo
117a0 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e  undup.  If xRoun
117b0 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a  dup returns 0, .
117c0 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74  ** that causes t
117d0 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
117e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
117f0 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  on to fail..**.*
11800 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * The xInit meth
11810 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  od initializes t
11820 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
11830 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tor.  For exampl
11840 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
11850 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
11860 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
11870 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
11880 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
11890 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
118a0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
118b0 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
118c0 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
118d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
118e0 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
118f0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
11900 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
11910 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
11920 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
11930 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
11940 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
11950 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
11960 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
11970 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
11980 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11990 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
119a0 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
119b0 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
119c0 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
119d0 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
119e0 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
119f0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
11a00 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
11a10 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
11a20 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
11a30 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
11a40 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
11a50 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
11a60 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
11a70 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
11a80 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
11a90 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
11aa0 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
11ab0 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
11ac0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11ad0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11af0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
11b00 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
11b10 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
11b20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
11b30 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
11b40 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
11b50 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
11b60 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
11b70 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
11b80 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
11b90 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
11ba0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
11bb0 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
11bc0 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
11bd0 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
11be0 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
11bf0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
11c00 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
11c10 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
11c20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
11c30 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
11c40 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
11c50 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11c60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11c70 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
11c80 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
11c90 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
11ca0 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
11cb0 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
11cc0 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
11cd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
11ce0 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
11cf0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
11d00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
11d10 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
11d20 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
11d30 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
11d40 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
11d50 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
11d60 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
11d70 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
11d80 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
11d90 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
11da0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
11db0 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
11dc0 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
11dd0 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
11de0 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
11df0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
11e00 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
11e10 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
11e20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
11e30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11e40 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
11e50 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
11e60 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
11e70 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
11e80 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
11e90 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
11ea0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
11eb0 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
11ec0 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
11ed0 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
11ee0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
11ef0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
11f00 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
11f10 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11f20 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
11f30 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
11f40 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11f50 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11f60 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
11f70 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11f80 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
11f90 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
11fa0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
11fb0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
11fc0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
11fd0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
11fe0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
11ff0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
12000 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
12010 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
12020 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
12030 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
12040 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
12050 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
12060 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
12070 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
12080 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
12090 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
120a0 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
120b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
120c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
120d0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
120e0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
120f0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
12100 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
12110 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
12120 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
12130 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
12140 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
12150 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
12160 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
12170 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
12180 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
12190 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
121a0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
121b0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
121c0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
121d0 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
121e0 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
121f0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
12200 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
12210 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
12220 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
12230 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
12240 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
12250 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
12260 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12270 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
12280 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
12290 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
122a0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
122b0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
122c0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
122d0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
122e0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
122f0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
12300 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
12310 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
12320 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
12330 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
12340 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12350 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
12360 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
12370 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12380 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
12390 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
123a0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
123b0 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
123c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
123d0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
123e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
123f0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
12400 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
12410 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
12420 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
12430 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
12440 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
12450 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
12460 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
12470 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
12480 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
12490 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
124a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
124b0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
124c0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
124d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
124e0 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
124f0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
12500 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
12510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12520 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
12530 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
12540 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
12550 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
12560 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
12570 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
12580 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
12590 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
125a0 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
125b0 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
125c0 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
125d0 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
125e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125f0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
12600 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
12610 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12620 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
12630 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
12640 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
12650 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
12660 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
12670 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
12680 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
12690 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
126a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
126b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
126c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
126d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
126e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
126f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
12700 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
12710 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
12720 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
12730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12740 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
12750 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12760 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
12770 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
12780 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
12790 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
127a0 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
127b0 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
127c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
127d0 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
127e0 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
127f0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
12800 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
12810 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
12820 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
12830 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
12840 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
12850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
12860 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
12870 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
12880 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
12890 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
128a0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
128b0 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
128c0 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
128d0 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
128e0 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
128f0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
12900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12910 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12920 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
12930 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
12940 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
12950 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
12960 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
12970 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
12980 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
12990 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
129a0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
129b0 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
129c0 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
129d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
129e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
129f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12a00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12a10 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12a20 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12a30 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
12a40 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
12a50 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
12a60 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12a70 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12a80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12a90 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12aa0 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12ab0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12ac0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
12ad0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12ae0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12af0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12b00 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
12b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
12b20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12b30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12b40 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  G_MALLOC option 
12b50 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12b60 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12b70 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
12b80 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
12b90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12ba0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12bb0 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ture..** The arg
12bc0 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12bd0 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12be0 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
12bf0 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12c00 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
12c10 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68  n place of.** th
12c20 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
12c30 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69  ion routines bui
12c40 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29  lt into SQLite.)
12c50 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a  ^ ^SQLite makes.
12c60 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  ** its own priva
12c70 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63  te copy of the c
12c80 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
12c90 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12ca0 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  ds] structure.**
12cb0 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c   before the [sql
12cc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63  ite3_config()] c
12cd0 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64  all returns.</dd
12ce0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12d00 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12d10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c  ONFIG_GETMALLOC<
12d20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12d30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
12d40 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  _GETMALLOC optio
12d50 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12d60 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
12d70 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
12d80 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
12d90 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12da0 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
12db0 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73  cture..** The [s
12dc0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
12dd0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
12de0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
12df0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
12e00 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
12e10 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
12e20 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
12e30 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
12e40 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
12e50 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
12e60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
12e70 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
12e80 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
12e90 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
12ea0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
12eb0 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
12ec0 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
12ed0 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
12ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
12ef0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
12f00 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f10 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
12f20 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
12f30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12f40 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65  ATUS option take
12f50 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  s single argumen
12f60 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a  t of type int,.*
12f70 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  * interpreted as
12f80 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63   a boolean, whic
12f90 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
12fa0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
12fb0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72  tion of.** memor
12fc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
12fd0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
12fe0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12ff0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
13000 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68  .** disabled, th
13010 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  e following SQLi
13020 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
13030 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
13040 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
13050 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
13060 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
13070 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
13080 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
13090 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
130a0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
130b0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
130c0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
130d0 74 65 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a  te3_status64()].
130e0 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
130f0 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
13100 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
13110 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
13120 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
13130 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
13140 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
13150 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
13160 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
13170 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13180 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
13190 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
131a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
131b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
131c0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
131d0 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
131e0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
131f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
13200 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
13210 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65  RATCH option spe
13220 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
13230 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a  memory buffer.**
13240 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13250 20 75 73 65 20 66 6f 72 20 73 63 72 61 74 63 68   use for scratch
13260 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72   memory.  ^(Ther
13270 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
13280 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49  ments.** to SQLI
13290 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
132a0 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  H:  A pointer an
132b0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
132c0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
132d0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
132e0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
132f0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
13300 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
13310 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
13320 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
13330 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
13340 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
13350 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
13360 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66   (N).)^.** The f
13370 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
13380 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
13390 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
133a0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
133b0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
133c0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
133d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
133e0 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68   not use more th
133f0 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62  an one scratch b
13400 75 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61  uffers per threa
13410 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  d..** ^SQLite wi
13420 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65 73 74  ll never request
13430 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
13440 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
13450 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
13460 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
13470 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   size..** ^If SQ
13480 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
13490 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
134a0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
134b0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
134c0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
134d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
134e0 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
134f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13500 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
13510 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
13520 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20  y needed.<p>.** 
13530 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63  ^When the applic
13540 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61  ation provides a
13550 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72  ny amount of scr
13560 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e  atch memory usin
13570 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  g.** SQLITE_CONF
13580 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69  IG_SCRATCH, SQLi
13590 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65  te avoids unnece
135a0 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b  ssary large.** [
135b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68  sqlite3_malloc|h
135c0 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d  eap allocations]
135d0 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65  ..** This can he
135e0 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66  lp [Robson proof
135f0 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20  |prevent memory 
13600 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
13610 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70  res] due to heap
13620 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f  .** fragmentatio
13630 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20  n in low-memory 
13640 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
13650 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
13660 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13670 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
13680 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
13690 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
136a0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
136b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
136c0 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  HE option specif
136d0 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f  ies a memory poo
136e0 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  l.** that SQLite
136f0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
13700 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13710 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13720 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13730 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13740 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13750 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13760 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66  on is a no-op if
13770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
13780 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
13790 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
137a0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
137b0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
137c0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e  CONFIG_PCACHE2].
137d0 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
137e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
137f0 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
13800 50 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69  PAGECACHE: A poi
13810 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74  nter to.** 8-byt
13820 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  e aligned memory
13830 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a   (pMem), the siz
13840 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 63  e of each page c
13850 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a  ache line (sz),.
13860 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ** and the numbe
13870 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73  r of cache lines
13880 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20   (N)..** The sz 
13890 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
138a0 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  be the size of t
138b0 68 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62  he largest datab
138c0 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70  ase page.** (a p
138d0 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77  ower of two betw
138e0 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33  een 512 and 6553
138f0 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74  6) plus some ext
13900 72 61 20 62 79 74 65 73 20 66 6f 72 20 65 61 63  ra bytes for eac
13910 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
13920 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  .  ^The number o
13930 66 20 65 78 74 72 61 20 62 79 74 65 73 20 6e 65  f extra bytes ne
13940 65 64 65 64 20 62 79 20 74 68 65 20 70 61 67 65  eded by the page
13950 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62   header.** can b
13960 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
13970 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ng [SQLITE_CONFI
13980 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e  G_PCACHE_HDRSZ].
13990 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  .** ^It is harml
139a0 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
139b0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
139c0 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a  y,.** for the sz
139d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
139e0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63   larger than nec
139f0 65 73 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65  essary.  The pMe
13a00 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  m.** argument mu
13a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
13a20 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  ULL pointer or a
13a30 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
13a40 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
13a50 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
13a60 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
13a70 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69  N bytes, otherwi
13a80 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  se.** subsequent
13a90 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
13aa0 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e  efined..** ^When
13ab0 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c   pMem is not NUL
13ac0 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73  L, SQLite will s
13ad0 74 72 69 76 65 20 74 6f 20 75 73 65 20 74 68 65  trive to use the
13ae0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
13af0 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70  .** to satisfy p
13b00 61 67 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c  age cache needs,
13b10 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f   falling back to
13b20 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13b30 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65  ()] if.** a page
13b40 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c   cache line is l
13b50 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79  arger than sz by
13b60 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66  tes or if all of
13b70 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72   the pMem buffer
13b80 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74 65 64  .** is exhausted
13b90 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73  ..** ^If pMem is
13ba0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e   NULL and N is n
13bb0 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61  on-zero, then ea
13bc0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
13bd0 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61  ection.** does a
13be0 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61  n initial bulk a
13bf0 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61  llocation for pa
13c00 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a  ge cache memory.
13c10 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
13c20 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69  _malloc()] suffi
13c30 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68  cient for N cach
13c40 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20  e lines if N is 
13c50 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f  positive or.** o
13c60 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20  f -1024*N bytes 
13c70 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65  if N is negative
13c80 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  , . ^If addition
13c90 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13ca0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13cb0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13cc0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65   provided by the
13cd0 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f   initial.** allo
13ce0 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c  cation, then SQL
13cf0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
13d00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
13d10 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61  eparately for ea
13d20 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  ch.** additional
13d30 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64   cache line. </d
13d40 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13d50 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
13d60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13d70 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
13d80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
13d90 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
13da0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
13db0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
13dc0 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c  fer .** that SQL
13dd0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72  ite will use for
13de0 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61   all of its dyna
13df0 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
13e00 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62  ation needs.** b
13e10 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76  eyond those prov
13e20 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c  ided for by [SQL
13e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
13e40 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49  CH] and.** [SQLI
13e50 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
13e60 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51  CHE]..** ^The SQ
13e70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
13e80 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
13e90 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c  available if SQL
13ea0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a  ite is compiled.
13eb0 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72 20 5b  ** with either [
13ec0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
13ed0 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54  MSYS3] or [SQLIT
13ee0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
13ef0 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  ] and returns.**
13f00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
13f10 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72  if invoked other
13f20 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20  wise..** ^There 
13f30 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
13f40 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  nts to SQLITE_CO
13f50 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e  NFIG_HEAP:.** An
13f60 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13f70 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
13f80 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
13f90 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
13fa0 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
13fb0 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
13fc0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
13fd0 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
13fe0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13ff0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
14000 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
14010 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
14020 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
14030 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
14040 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
14050 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
14060 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
14070 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
14080 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
14090 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
140a0 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
140b0 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
140c0 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
140d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
140e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
140f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
14100 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
14110 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
14120 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14130 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
14140 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14150 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14160 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
14170 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
14180 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
14190 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
141a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
141b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
141c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
141d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
141e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
141f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
14200 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
14210 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
14220 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
14230 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
14240 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14250 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
14260 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14270 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
14280 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14290 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f  E_CONFIG_MUTEX o
142a0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
142b0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
142c0 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ich is a.** poin
142d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
142e0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
142f0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14300 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
14310 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
14320 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69  cifies alternati
14330 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
14340 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
14350 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61  e used.** in pla
14360 63 65 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ce the mutex rou
14370 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
14380 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
14390 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
143a0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
143b0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
143c0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
143d0 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
143e0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
143f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14400 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
14410 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14420 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14430 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14440 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14450 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14460 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14470 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
14480 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
14490 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
144a0 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
144b0 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
144c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
144d0 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
144e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
144f0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
14500 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
14510 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
14520 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
14530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14540 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
14550 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14560 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
14570 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
14580 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
14590 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  TEX option takes
145a0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
145b0 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61  nt which.** is a
145c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
145d0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
145e0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
145f0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
14600 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
14610 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
14620 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
14630 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
14640 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
14650 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  ned mutex routin
14660 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
14670 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
14680 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
14690 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61   default mutex a
146a0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
146b0 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
146c0 70 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61  pper used to tra
146d0 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66  ck mutex usage f
146e0 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a  or performance.*
146f0 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74  * profiling or t
14700 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d  esting, for exam
14710 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ple.   ^If SQLit
14720 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14730 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
14740 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
14750 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14760 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
14770 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
14780 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78  the entire mutex
14790 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73  ing subsystem is
147a0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
147b0 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63  e build and henc
147c0 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  e calls to.** [s
147d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
147e0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
147f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
14800 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14810 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14820 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14830 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14840 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14850 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e  LOOKASIDE]] <dt>
14860 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14870 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
14880 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14890 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
148a0 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  DE option takes 
148b0 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
148c0 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20  at determine.** 
148d0 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
148e0 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65   of lookaside me
148f0 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61  mory on each [da
14900 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14910 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  n]..** The first
14920 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
14930 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
14940 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14950 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
14960 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
14970 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
14980 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
14990 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
149a0 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49  ction.)^  ^(SQLI
149b0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
149c0 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20  IDE.** sets the 
149d0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
149e0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
149f0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
14a00 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
14a10 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c  * option to [sql
14a20 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14a30 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
14a40 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
14a50 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
14a60 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
14a70 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
14a80 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
14a90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14aa0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
14ab0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14ac0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
14ad0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
14ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
14af0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14b00 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
14b10 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
14b20 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14b30 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14b40 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
14b50 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
14b60 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61  s.** the interfa
14b70 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ce to a custom p
14b80 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
14b90 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e  entation.)^.** ^
14ba0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
14bb0 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
14bc0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
14bd0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64  ds2] object.</dd
14be0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
14c00 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
14c10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
14c20 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14c30 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14c40 49 47 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70  IG_GETPCACHE2 op
14c50 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
14c60 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
14c70 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
14c80 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65  er to an [sqlite
14c90 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ca0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  2] object.  SQLi
14cb0 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20  te copies of.** 
14cc0 74 68 65 20 63 75 72 72 65 6e 74 20 70 61 67 65  the current page
14cd0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
14ce0 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
14cf0 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
14d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14d10 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
14d20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14d30 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54  G</dt>.** <dd> T
14d40 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14d50 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75  _LOG option is u
14d60 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
14d70 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67   the SQLite.** g
14d80 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67  lobal [error log
14d90 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49  ]..** (^The SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
14db0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
14dc0 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e  rguments: a poin
14dd0 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63  ter to a.** func
14de0 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c  tion with a call
14df0 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f   signature of vo
14e00 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  id(*)(void*,int,
14e10 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a  const char*), .*
14e20 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20  * and a pointer 
14e30 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65  to void. ^If the
14e40 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
14e50 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69  r is not NULL, i
14e60 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20  t is.** invoked 
14e70 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  by [sqlite3_log(
14e80 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61  )] to process ea
14e90 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74  ch logging event
14ea0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75  .  ^If the.** fu
14eb0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
14ec0 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c  s NULL, the [sql
14ed0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65  ite3_log()] inte
14ee0 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20  rface becomes a 
14ef0 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76  no-op..** ^The v
14f00 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74  oid pointer that
14f10 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   is the second a
14f20 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54  rgument to SQLIT
14f30 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a  E_CONFIG_LOG is.
14f40 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67  ** passed throug
14f50 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70  h as the first p
14f60 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14f70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
14f80 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75  ned logger.** fu
14f90 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20  nction whenever 
14fa0 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73  that function is
14fb0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20   invoked.  ^The 
14fc0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14fd0 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65   to.** the logge
14fe0 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20  r function is a 
14ff0 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73  copy of the firs
15000 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
15010 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
15020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  .** [sqlite3_log
15030 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20  ()] call and is 
15040 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61  intended to be a
15050 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
15060 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  r an.** [extende
15070 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20  d result code]. 
15080 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
15090 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20  meter passed to 
150a0 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a  the logger is.**
150b0 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74   log message aft
150c0 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69  er formatting vi
150d0 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  a [sqlite3_snpri
150e0 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53  ntf()]..** The S
150f0 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e  QLite logging in
15100 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
15110 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f  eentrant; the lo
15120 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gger function.**
15130 20 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65   supplied by the
15140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
15150 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79  t not invoke any
15160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15170 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69  e..** In a multi
15180 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63  -threaded applic
15190 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69  ation, the appli
151a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
151b0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
151c0 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  n must be thread
151d0 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  safe. </dd>.**.*
151e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
151f0 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_URI]] <dt>SQLI
15200 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a  TE_CONFIG_URI.**
15210 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54   <dd>^(The SQLIT
15220 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74  E_CONFIG_URI opt
15230 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15240 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
15250 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e  ype int..** If n
15260 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52  on-zero, then UR
15270 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15280 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
15290 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
152a0 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65   is zero,.** the
152b0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
152c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
152d0 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68  led.)^ ^If URI h
152e0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
152f0 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20  lly.** enabled, 
15300 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61  all filenames pa
15310 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33  ssed to [sqlite3
15320 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
15330 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a  e3_open_v2()],.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
15350 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
15360 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
15370 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
15380 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
15390 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
153a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
153b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
153c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
153d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
153e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
153f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
15400 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
15410 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
15420 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
15430 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
15440 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
15450 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
15460 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
15470 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
15480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15490 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
154a0 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
154b0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
154c0 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
154d0 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
154e0 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
154f0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
15500 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
15510 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
15520 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
15530 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15540 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
15550 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
15560 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
15570 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
15580 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
15590 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
155a0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70  NG_INDEX_SCAN op
155b0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
155c0 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61  gle integer.** a
155d0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
155e0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
155f0 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64  a boolean in ord
15600 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  er to enable or 
15610 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75  disable.** the u
15620 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
15630 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
15640 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74  table scans in t
15650 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a  he query optimiz
15660 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  er..** ^The defa
15670 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64  ult setting is d
15680 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20  etermined.** by 
15690 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f  the [SQLITE_ALLO
156a0 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  W_COVERING_INDEX
156b0 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74  _SCAN] compile-t
156c0 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69  ime option, or i
156d0 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61  s "on".** if tha
156e0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
156f0 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ption is omitted
15700 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79  ..** The ability
15710 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20   to disable the 
15720 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
15730 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c  indices for full
15740 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20   table scans.** 
15750 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20  is because some 
15760 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65  incorrectly code
15770 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61  d legacy applica
15780 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66  tions might malf
15790 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20  unction.** when 
157a0 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
157b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72   is enabled.  Pr
157c0 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c  oviding the abil
157d0 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c  ity to.** disabl
157e0 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  e the optimizati
157f0 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c  on allows the ol
15800 64 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69  der, buggy appli
15810 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77  cation code to w
15820 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63  ork.** without c
15830 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20  hange even with 
15840 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
15850 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
15860 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15870 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
15880 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
15890 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
158b0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
158c0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
158d0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
158e0 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
158f0 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
15900 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
15910 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
15920 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
15930 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
15940 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
15950 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64   no-ops..** </dd
15960 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15970 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d  _CONFIG_SQLLOG]]
15980 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15990 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20  ONFIG_SQLLOG.** 
159a0 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20  <dd>This option 
159b0 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
159c0 65 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63  e if sqlite is c
159d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
159e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
159f0 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70  LE_SQLLOG] pre-p
15a00 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64  rocessor macro d
15a10 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73  efined. The firs
15a20 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  t argument shoul
15a30 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65  d.** be a pointe
15a40 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20  r to a function 
15a50 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28  of type void(*)(
15a60 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63  void*,sqlite3*,c
15a70 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29  onst char*, int)
15a80 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
15a90 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70  should be of typ
15aa0 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63  e (void*). The c
15ab0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
15ac0 65 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72  ed by the librar
15ad0 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65  y.** in three se
15ae0 70 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61  parate circumsta
15af0 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64  nces, identified
15b00 20 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61   by the value pa
15b10 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66  ssed as the.** f
15b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e  ourth parameter.
15b30 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
15b40 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74  arameter is 0, t
15b50 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
15b60 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70   connection.** p
15b70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
15b80 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73  ond argument has
15b90 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65   just been opene
15ba0 64 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67  d. The third arg
15bb0 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20  ument.** points 
15bc0 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74  to a buffer cont
15bd0 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20  aining the name 
15be0 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61  of the main data
15bf0 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68  base file. If th
15c00 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
15c10 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e  meter is 1, then
15c20 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
15c30 6e 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72  nt that the thir
15c40 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70  d parameter.** p
15c50 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73  oints to has jus
15c60 74 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e  t been executed.
15c70 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72   Or, if the four
15c80 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
15c90 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63  2, then.** the c
15ca0 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20  onnection being 
15cb0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
15cc0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
15cd0 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20  s being closed. 
15ce0 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  The.** third par
15cf0 61 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64  ameter is passed
15d00 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61   NULL In this ca
15d10 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  se.  An example 
15d20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a  of using this.**
15d30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d40 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65  ption can be see
15d50 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73  n in the "test_s
15d60 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20  qllog.c" source 
15d70 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63  file in.** the c
15d80 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20  anonical SQLite 
15d90 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64  source tree.</dd
15da0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15db0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15dc0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
15dd0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15de0 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54  ZE.** <dd>^SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49  E_CONFIG_MMAP_SI
15e00 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d  ZE takes two 64-
15e10 62 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c  bit integer (sql
15e20 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75  ite3_int64) valu
15e30 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74  es.** that are t
15e40 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20  he default mmap 
15e50 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20  size limit (the 
15e60 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
15e70 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d  for.** [PRAGMA m
15e80 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74  map_size]) and t
15e90 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15ea0 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  ed mmap size lim
15eb0 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61  it..** ^The defa
15ec0 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20  ult setting can 
15ed0 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79  be overridden by
15ee0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
15ef0 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a  onnection using.
15f00 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50  ** either the [P
15f10 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
15f20 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20   command, or by 
15f30 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51  using the.** [SQ
15f40 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
15f50 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  SIZE] file contr
15f60 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d  ol.  ^(The maxim
15f70 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15f80 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  size.** will be 
15f90 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74  silently truncat
15fa0 65 64 20 69 66 20 6e 65 63 65 73 73 61 72 79 20  ed if necessary 
15fb0 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65 73 20  so that it does 
15fc0 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a  not exceed the.*
15fd0 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  * compile-time m
15fe0 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15ff0 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
16000 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
16010 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
16020 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
16030 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
16040 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
16050 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
16060 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
16070 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
16080 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
16090 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
160a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
160b0 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
160c0 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
160d0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
160e0 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
160f0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
16100 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
16110 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  E option is only
16120 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
16130 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
16140 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20  led for Windows 
16150 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
16160 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
16170 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
16180 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e  ro.** defined. ^
16190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
161a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b  N32_HEAPSIZE tak
161b0 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69  es a 32-bit unsi
161c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c  gned integer val
161d0 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69  ue.** that speci
161e0 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  fies the maximum
161f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65   size of the cre
16200 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a  ated heap..**.**
16210 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16220 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a  _PCACHE_HDRSZ]].
16230 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
16240 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
16250 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16270 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20  HE_HDRSZ option 
16280 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70  takes a single p
16290 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
162a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
162b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
162c0 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61   writes into tha
162d0 74 20 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75  t integer the nu
162e0 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a  mber of extra.**
162f0 20 62 79 74 65 73 20 70 65 72 20 70 61 67 65 20   bytes per page 
16300 72 65 71 75 69 72 65 64 20 66 6f 72 20 65 61 63  required for eac
16310 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54  h page in [SQLIT
16320 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
16330 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75  HE]..** The amou
16340 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70 61 63  nt of extra spac
16350 65 20 72 65 71 75 69 72 65 64 20 63 61 6e 20 63  e required can c
16360 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20  hange depending 
16370 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c  on the compiler,
16380 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66  .** target platf
16390 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20  orm, and SQLite 
163a0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  version..**.** [
163b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
163c0 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  MASZ]].** <dt>SQ
163d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
163e0 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  Z.** <dd>^The SQ
163f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16400 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  Z option takes a
16410 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65   single paramete
16420 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e  r which.** is an
16430 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65   unsigned intege
16440 72 20 61 6e 64 20 73 65 74 73 20 74 68 65 20 22  r and sets the "
16450 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  Minimum PMA Size
16460 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74  " for the multit
16470 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65  hreaded.** sorte
16480 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  r to that intege
16490 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  r.  The default 
164a0 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65  minimum PMA Size
164b0 20 69 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a   is set by the.*
164c0 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52  * [SQLITE_SORTER
164d0 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d  _PMASZ] compile-
164e0 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65  time option.  Ne
164f0 77 20 74 68 72 65 61 64 73 20 61 72 65 20 6c 61  w threads are la
16500 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c  unched.** to hel
16510 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72  p with sort oper
16520 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74  ations when mult
16530 69 74 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e  ithreaded sortin
16540 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20  g.** is enabled 
16550 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47  (using the [PRAG
16560 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d  MA threads] comm
16570 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f  and) and the amo
16580 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a  unt of content.*
16590 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65  * to be sorted e
165a0 78 63 65 65 64 73 20 74 68 65 20 70 61 67 65 20  xceeds the page 
165b0 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d  size times the m
165c0 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a  inimum of the.**
165d0 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73   [PRAGMA cache_s
165e0 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64  ize] setting and
165f0 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20   this value..** 
16600 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </dl>.*/.#define
16610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
16620 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20  INGLETHREAD  1  
16630 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
16640 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16650 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20  MULTITHREAD   2 
16660 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
16670 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16680 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33  _SERIALIZED    3
16690 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
166a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
166b0 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  G_MALLOC        
166c0 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  4  /* sqlite3_me
166d0 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
166e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
166f0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20  FIG_GETMALLOC   
16700 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    5  /* sqlite3_
16710 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
16720 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16730 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20  ONFIG_SCRATCH   
16740 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c      6  /* void*,
16750 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
16760 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16770 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
16780 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64  E     7  /* void
16790 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
167a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167b0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20  TE_CONFIG_HEAP  
167c0 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f          8  /* vo
167d0 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  id*, int nByte, 
167e0 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69  int min */.#defi
167f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16800 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39  _MEMSTATUS     9
16810 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a    /* boolean */.
16820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16830 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20  ONFIG_MUTEX     
16840 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65     10  /* sqlite
16850 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16870 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
16880 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71  EX     11  /* sq
16890 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
168a0 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69  ods* */./* previ
168b0 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e  ously SQLITE_CON
168c0 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31  FIG_CHUNKALLOC 1
168d0 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75  2 which is now u
168e0 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69  nused. */ .#defi
168f0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16900 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33  _LOOKASIDE    13
16910 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a    /* int int */.
16920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16930 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20  ONFIG_PCACHE    
16940 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20     14  /* no-op 
16950 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16960 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
16970 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d  HE    15  /* no-
16980 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
16990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
169a0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
169b0 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
169c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
169d0 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
169e0 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
169f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16a00 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20  CONFIG_PCACHE2  
16a10 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74      18  /* sqlit
16a20 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
16a30 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
16a40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16a50 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a  PCACHE2   19  /*
16a60 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f   sqlite3_pcache_
16a70 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65  methods2* */.#de
16a80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16a90 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
16aa0 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e  X_SCAN 20  /* in
16ab0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
16ac0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f  ITE_CONFIG_SQLLO
16ad0 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78  G       21  /* x
16ae0 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f  Sqllog, void* */
16af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16b00 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16b10 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74      22  /* sqlit
16b20 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65  e3_int64, sqlite
16b30 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69  3_int64 */.#defi
16b40 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16b50 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16b60 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20       23  /* int 
16b70 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65  nByte */.#define
16b80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
16b90 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20  CACHE_HDRSZ     
16ba0 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70     24  /* int *p
16bb0 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  sz */.#define SQ
16bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
16bd0 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Z               
16be0 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20  25  /* unsigned 
16bf0 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a  int szPma */../*
16c00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
16c10 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
16c20 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
16c30 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
16c40 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
16c50 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
16c60 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
16c70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
16c80 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
16c90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
16ca0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
16cb0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
16cc0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
16cd0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
16ce0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
16cf0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
16d00 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
16d10 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
16d20 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
16d30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
16d40 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
16d50 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
16d60 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
16d70 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
16d80 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
16d90 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16da0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
16db0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
16dc0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
16dd0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16de0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
16df0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
16e00 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
16e10 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
16e20 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
16e30 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
16e40 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
16e50 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
16e60 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
16e70 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
16e80 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
16e90 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
16ea0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
16eb0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
16ec0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
16ed0 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
16ee0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16ef0 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
16f00 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
16f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
16f20 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
16f30 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
16f40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
16f50 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
16f60 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
16f70 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
16f80 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
16f90 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
16fa0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
16fb0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
16fc0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
16fd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16fe0 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
16ff0 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
17000 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
17010 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
17020 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
17030 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
17040 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
17050 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
17060 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17070 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17080 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
17090 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
170a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
170b0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
170c0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
170d0 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
170e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
170f0 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
17100 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
17110 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
17120 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
17130 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
17140 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
17150 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
17160 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
17170 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
17180 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17190 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
171a0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
171b0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
171c0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
171d0 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
171e0 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
171f0 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
17200 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
17210 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
17220 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
17230 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
17240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17250 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
17260 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
17270 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
17280 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
17290 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
172a0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
172b0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
172c0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
172d0 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
172e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
172f0 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
17300 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17310 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
17320 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
17330 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17340 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17350 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
17360 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
17370 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
17380 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
17390 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
173a0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
173b0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
173c0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
173d0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
173e0 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
173f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
17400 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
17410 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
17420 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
17430 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
17440 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
17450 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
17460 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
17470 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
17480 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
17490 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
174a0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
174b0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
174c0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
174d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
174e0 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
174f0 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
17500 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
17510 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
17520 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
17530 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
17540 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17550 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
17560 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
17570 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
17580 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
17590 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
175a0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
175b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
175c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
175d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
175e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
175f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
17600 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
17610 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
17620 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
17630 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
17640 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
17650 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
17660 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17670 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17680 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17690 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
176a0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
176b0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
176c0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
176d0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
176e0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
176f0 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
17700 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
17710 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
17720 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
17730 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
17740 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
17750 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
17760 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
17770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17780 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
17790 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
177a0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
177b0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
177c0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
177d0 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
177e0 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
177f0 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
17800 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
17810 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
17820 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
17830 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
17840 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
17850 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
17860 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
17870 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
17880 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
17890 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
178a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
178b0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
178c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
178d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
178e0 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
178f0 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
17900 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
17910 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
17920 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
17930 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
17940 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
17950 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
17960 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
17970 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
17980 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
17990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
179a0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
179b0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
179c0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
179d0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
179e0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
179f0 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
17a00 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
17a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
17a20 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
17a30 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
17a40 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
17a50 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
17a60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
17a70 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
17a80 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
17a90 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
17aa0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
17ab0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
17ac0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
17ad0 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Rowid.** METHOD:
17ae0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17af0 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f  Each entry in mo
17b00 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73  st SQLite tables
17b10 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49   (except for [WI
17b20 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62  THOUT ROWID] tab
17b30 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e  les).** has a un
17b40 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
17b50 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
17b60 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
17b70 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
17b80 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
17b90 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
17ba0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
17bb0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
17bc0 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
17bd0 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
17be0 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
17bf0 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
17c00 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
17c10 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
17c20 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
17c30 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
17c40 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
17c50 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
17c60 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
17c70 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
17c80 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
17c90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
17ca0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
17cb0 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72  t_rowid(D) inter
17cc0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
17cd0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
17ce0 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  .** most recent 
17cf0 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
17d00 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64  RT] into a rowid
17d10 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75   table or [virtu
17d20 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20  al table].** on 
17d30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17d40 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72  ion D..** ^Inser
17d50 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54  ts into [WITHOUT
17d60 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61   ROWID] tables a
17d70 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e  re not recorded.
17d80 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
17d90 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20  ssful [INSERT]s 
17da0 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65  into rowid table
17db0 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f  s.** have ever o
17dc0 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64  ccurred on the d
17dd0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17de0 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73  on D, .** then s
17df0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17e00 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75  rt_rowid(D) retu
17e10 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
17e20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
17e30 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
17e40 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68   trigger or with
17e50 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  in a [virtual ta
17e60 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20  ble].** method, 
17e70 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
17e80 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68  e will return th
17e90 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
17ea0 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77   inserted.** row
17eb0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
17ec0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
17ed0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
17ee0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42  is running..** B
17ef0 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67  ut once the trig
17f00 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
17f10 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73  able method ends
17f20 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  , the value retu
17f30 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73  rned .** by this
17f40 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73   routine reverts
17f50 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20   to what it was 
17f60 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67  before the trigg
17f70 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a  er or virtual.**
17f80 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65   table method be
17f90 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  gan.)^.**.** ^An
17fa0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
17fb0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
17fc0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
17fd0 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
17fe0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
17ff0 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
18000 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
18010 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
18020 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
18030 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
18040 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
18050 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
18060 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
18070 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
18080 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
18090 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
180a0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
180b0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
180c0 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
180d0 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
180e0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
180f0 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
18100 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
18110 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
18120 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
18130 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
18140 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
18150 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
18160 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
18170 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
18180 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
18190 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
181a0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
181b0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
181c0 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
181d0 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
181e0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
181f0 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
18200 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
18210 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
18220 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
18230 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
18240 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
18250 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
18260 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
18270 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
18280 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
18290 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
182a0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
182b0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
182c0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
182d0 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
182e0 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
182f0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
18300 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18310 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
18320 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18330 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
18340 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
18350 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
18360 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
18370 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
18380 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
18390 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
183a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
183b0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
183c0 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
183d0 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
183e0 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
183f0 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
18400 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
18410 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
18420 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
18430 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
18440 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
18450 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
18460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18470 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
18480 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
18490 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
184a0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
184b0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
184c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
184d0 20 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20   rows modified, 
184e0 69 6e 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64  inserted or.** d
184f0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
18500 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
18510 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
18520 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a  DATE or DELETE.*
18530 2a 20 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74  * statement on t
18540 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18550 65 63 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64  ection specified
18560 20 62 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   by the only par
18570 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63  ameter..** ^Exec
18580 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  uting any other 
18590 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74  type of SQL stat
185a0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d  ement does not m
185b0 6f 64 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a  odify the value.
185c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ** returned by t
185d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  his function..**
185e0 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65  .** ^Only change
185f0 73 20 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20  s made directly 
18600 62 79 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55  by the INSERT, U
18610 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
18620 73 74 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a  statement are.**
18630 20 63 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75   considered - au
18640 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
18650 63 61 75 73 65 64 20 62 79 20 5b 43 52 45 41 54  caused by [CREAT
18660 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
18670 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65  gers], .** [fore
18680 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
18690 20 6f 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f   or [REPLACE] co
186a0 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74  nstraint resolut
186b0 69 6f 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ion are not coun
186c0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e  ted..** .** Chan
186d0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
186e0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
186f0 65 64 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45  ed by .** [INSTE
18700 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20  AD OF trigger | 
18710 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
18720 65 72 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ers] are not cou
18730 6e 74 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65  nted. ^The value
18740 20 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79   .** returned by
18750 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18760 28 29 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61  () immediately a
18770 66 74 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20  fter an INSERT, 
18780 55 50 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45  UPDATE or .** DE
18790 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72  LETE statement r
187a0 75 6e 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20  un on a view is 
187b0 61 6c 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c  always zero. Onl
187c0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74  y changes made t
187d0 6f 20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65  o real .** table
187e0 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
187f0 2a 0a 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20  *.** Things are 
18800 6d 6f 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64  more complicated
18810 20 69 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   if the sqlite3_
18820 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69  changes() functi
18830 6f 6e 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65  on is.** execute
18840 64 20 77 68 69 6c 65 20 61 20 74 72 69 67 67 65  d while a trigge
18850 72 20 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e  r program is run
18860 6e 69 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68  ning. This may h
18870 61 70 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20  appen if the.** 
18880 70 72 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65  program uses the
18890 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
188a0 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66  function], or if
188b0 20 73 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c   some other call
188c0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
188d0 20 69 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33   invokes sqlite3
188e0 5f 63 68 61 6e 67 65 73 28 29 20 64 69 72 65 63  _changes() direc
188f0 74 6c 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79  tly. Essentially
18900 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  :.** .** <ul>.**
18910 20 20 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65     <li> ^(Before
18920 20 65 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67   entering a trig
18930 67 65 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20  ger program the 
18940 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
18950 79 0a 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69  y.**        sqli
18960 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
18970 6e 63 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e  nction is saved.
18980 20 41 66 74 65 72 20 74 68 65 20 74 72 69 67 67   After the trigg
18990 65 72 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20  er program .**  
189a0 20 20 20 20 20 20 68 61 73 20 66 69 6e 69 73 68        has finish
189b0 65 64 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  ed, the original
189c0 20 76 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72   value is restor
189d0 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c  ed.)^.** .**   <
189e0 6c 69 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74  li> ^(Within a t
189f0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65  rigger program e
18a00 61 63 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ach INSERT, UPDA
18a10 54 45 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a  TE and DELETE .*
18a20 2a 20 20 20 20 20 20 20 20 73 74 61 74 65 6d 65  *        stateme
18a30 6e 74 20 73 65 74 73 20 74 68 65 20 76 61 6c 75  nt sets the valu
18a40 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
18a50 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18a60 0a 2a 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20  .**        upon 
18a70 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f  completion as no
18a80 72 6d 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c  rmal. Of course,
18a90 20 74 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c   this value will
18aa0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a   not include .**
18ab0 20 20 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e          any chan
18ac0 67 65 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79  ges performed by
18ad0 20 73 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61   sub-triggers, a
18ae0 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  s the sqlite3_ch
18af0 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18b00 20 20 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65     value will be
18b10 20 73 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f   saved and resto
18b20 72 65 64 20 61 66 74 65 72 20 65 61 63 68 20 73  red after each s
18b30 75 62 2d 74 72 69 67 67 65 72 20 68 61 73 20 72  ub-trigger has r
18b40 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  un.)^.** </ul>.*
18b50 2a 20 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e  * .** ^This mean
18b60 73 20 74 68 61 74 20 69 66 20 74 68 65 20 63 68  s that if the ch
18b70 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18b80 74 69 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72  tion (or similar
18b90 29 20 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20  ) is used.** by 
18ba0 74 68 65 20 66 69 72 73 74 20 49 4e 53 45 52 54  the first INSERT
18bb0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18bc0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18bd0 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69  hin a trigger, i
18be0 74 20 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  t .** returns th
18bf0 65 20 76 61 6c 75 65 20 61 73 20 73 65 74 20 77  e value as set w
18c00 68 65 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  hen the calling 
18c10 73 74 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20  statement began 
18c20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49  executing..** ^I
18c30 66 20 69 74 20 69 73 20 75 73 65 64 20 62 79 20  f it is used by 
18c40 74 68 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75  the second or su
18c50 62 73 65 71 75 65 6e 74 20 73 75 63 68 20 73 74  bsequent such st
18c60 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61  atement within a
18c70 20 74 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f   trigger .** pro
18c80 67 72 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20  gram, the value 
18c90 72 65 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74  returned reflect
18ca0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
18cb0 72 6f 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79  rows modified by
18cc0 20 74 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75   the .** previou
18cd0 73 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  s INSERT, UPDATE
18ce0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
18cf0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
18d00 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
18d10 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
18d20 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18d30 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
18d40 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
18d50 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
18d60 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
18d70 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
18d80 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
18d90 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
18da0 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
18db0 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
18dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
18dd0 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
18de0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
18df0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
18e00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18e10 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
18e20 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
18e30 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
18e40 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
18e50 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
18e60 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
18e70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
18e80 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
18e90 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
18ea0 65 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ed.** METHOD: sq
18eb0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
18ec0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
18ed0 6e 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  ns the total num
18ee0 62 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65  ber of rows inse
18ef0 72 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f  rted, modified o
18f00 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20  r.** deleted by 
18f10 61 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55  all [INSERT], [U
18f20 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54  PDATE] or [DELET
18f30 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f  E] statements co
18f40 6d 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65  mpleted.** since
18f50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18f60 6e 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65  nnection was ope
18f70 6e 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74  ned, including t
18f80 68 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73  hose executed as
18f90 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67  .** part of trig
18fa0 67 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45  ger programs. ^E
18fb0 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68  xecuting any oth
18fc0 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73  er type of SQL s
18fd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73  tatement.** does
18fe0 20 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20   not affect the 
18ff0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19000 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
19010 63 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a  changes()..** .*
19020 2a 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20  * ^Changes made 
19030 61 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65  as part of [fore
19040 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
19050 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e   are included in
19060 20 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62   the.** count, b
19070 75 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73  ut those made as
19080 20 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45   part of REPLACE
19090 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f   constraint reso
190a0 6c 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f  lution are.** no
190b0 74 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  t. ^Changes to a
190c0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
190d0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e  ntercepted by IN
190e0 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
190f0 73 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f  s .** are not co
19100 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65  unted..** .** Se
19110 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
19120 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
19130 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
19140 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
19150 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
19160 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
19170 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
19180 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
19190 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
191a0 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
191b0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
191c0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
191d0 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
191e0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
191f0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
19200 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
19210 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
19220 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
19230 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
19240 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
19250 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
19260 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
19270 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
19280 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
19290 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
192a0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
192b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
192c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
192d0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
192e0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
192f0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
19300 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
19310 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
19320 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
19330 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
19340 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
19350 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
19360 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
19370 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
19380 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
19390 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
193a0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
193b0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
193c0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
193d0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
193e0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
193f0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
19400 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
19410 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
19420 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
19430 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
19440 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
19450 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
19460 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
19470 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
19480 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
19490 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
194a0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
194b0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
194c0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
194d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
194e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
194f0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
19500 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
19510 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
19520 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
19530 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
19540 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
19550 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
19560 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
19570 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
19580 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
19590 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
195a0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
195b0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
195c0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
195d0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
195e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
195f0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
19600 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
19610 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
19620 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
19630 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
19640 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
19650 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
19660 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
19670 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
19680 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
19690 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
196a0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
196b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
196c0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
196d0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
196e0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
196f0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
19700 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
19710 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19720 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
19730 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
19740 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19750 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
19760 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
19770 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
19780 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
19790 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
197a0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
197b0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
197c0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
197d0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
197e0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
197f0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19800 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
19810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19820 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19830 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
19840 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
19850 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
19860 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
19870 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
19880 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
19890 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
198a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
198b0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
198c0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
198d0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
198e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
198f0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
19900 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
19910 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19920 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19930 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19940 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
19950 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
19960 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
19970 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
19980 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
19990 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
199a0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
199b0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
199c0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
199d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
199e0 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
199f0 4c 4c 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  LL sqlite3_inter
19a00 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
19a10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19a20 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
19a30 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
19a40 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
19a50 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
19a60 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
19a70 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
19a80 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
19a90 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
19aa0 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
19ab0 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
19ac0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
19ad0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
19ae0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
19af0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
19b00 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
19b10 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
19b20 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
19b30 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
19b40 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
19b50 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
19b60 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
19b70 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
19b80 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
19b90 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
19ba0 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
19bb0 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
19bc0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
19bd0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
19be0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
19bf0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
19c00 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
19c10 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
19c20 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
19c30 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
19c40 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
19c50 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
19c60 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
19c70 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
19c80 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
19c90 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
19ca0 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
19cb0 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
19cc0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
19cd0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
19ce0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
19cf0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
19d00 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
19d10 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
19d20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
19d30 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
19d40 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
19d50 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
19d60 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
19d70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
19d80 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
19d90 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
19da0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
19db0 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
19dc0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
19dd0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
19de0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
19df0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
19e00 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
19e10 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
19e20 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
19e30 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
19e40 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
19e50 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
19e60 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
19e70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
19e80 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
19e90 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
19ea0 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
19eb0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
19ec0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
19ed0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
19ee0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
19ef0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
19f00 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
19f10 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
19f20 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
19f30 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
19f40 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
19f50 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
19f60 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
19f70 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
19f80 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
19f90 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
19fa0 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
19fb0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
19fc0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
19fd0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
19fe0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
19ff0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1a000 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1a010 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1a020 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1a030 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1a040 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1a050 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1a060 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
1a070 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1a080 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
1a090 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
1a0a0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1a0b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1a0c0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1a0d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1a0e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a0f0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1a100 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1a110 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1a120 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
1a130 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
1a140 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e  lback} {busy han
1a150 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  dler}.** METHOD:
1a160 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
1a170 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1a180 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20  _handler(D,X,P) 
1a190 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63  routine sets a c
1a1a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a1b0 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74   X.** that might
1a1c0 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1a1d0 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e   argument P when
1a1e0 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d  ever.** an attem
1a1f0 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63  pt is made to ac
1a200 63 65 73 73 20 61 20 64 61 74 61 62 61 73 65 20  cess a database 
1a210 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64  table associated
1a220 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61   with.** [databa
1a230 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1a240 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68   when another th
1a250 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
1a260 73 73 20 68 61 73 20 74 68 65 20 74 61 62 6c 65  ss has the table
1a270 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20   locked..** The 
1a280 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a290 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  dler() interface
1a2a0 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   is used to impl
1a2b0 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65  ement.** [sqlite
1a2c0 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1a2d0 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75  ] and [PRAGMA bu
1a2e0 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a  sy_timeout]..**.
1a2f0 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  ** ^If the busy 
1a300 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1a310 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42  , then [SQLITE_B
1a320 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  USY].** is retur
1a330 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
1a340 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
1a350 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
1a360 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
1a370 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
1a380 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
1a390 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
1a3a0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
1a3b0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
1a3c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
1a3d0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
1a3e0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
1a3f0 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
1a400 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
1a410 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
1a420 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
1a430 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
1a440 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
1a450 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
1a460 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
1a470 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
1a480 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
1a490 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
1a4a0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
1a4b0 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73  invoked previous
1a4c0 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ly for the same 
1a4d0 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20  locking event.  
1a4e0 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20  ^If the.** busy 
1a4f0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1a500 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69   0, then no addi
1a510 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20  tional attempts 
1a520 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61  are made to.** a
1a530 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1a540 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42  se and [SQLITE_B
1a550 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64  USY] is returned
1a560 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69  .** to the appli
1a570 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  cation..** ^If t
1a580 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1a590 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1a5a0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1a5b0 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1a5c0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1a5d0 62 61 73 65 20 61 6e 64 20 74 68 65 20 63 79 63  base and the cyc
1a5e0 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1a5f0 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1a600 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1a610 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1a620 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1a630 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1a640 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1a650 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1a660 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1a670 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1a680 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1a690 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1a6a0 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1a6b0 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1a6c0 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1a6d0 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74  QLITE_BUSY].** t
1a6e0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
1a6f0 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76  n instead of inv
1a700 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75  oking the .** bu
1a710 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1a720 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1a730 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1a740 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1a750 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1a760 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1a770 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1a780 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1a790 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1a7a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a7b0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1a7c0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1a7d0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1a7e0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1a7f0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1a800 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1a810 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1a820 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1a830 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1a840 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1a850 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1a860 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1a870 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1a880 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1a890 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1a8a0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1a8b0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1a8c0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1a8d0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1a8e0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1a8f0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1a900 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1a910 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1a920 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1a930 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1a940 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1a950 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1a960 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1a970 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1a980 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1a990 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1a9a0 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1a9b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1a9c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1a9d0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1a9e0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1a9f0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
1aa00 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
1aa10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
1aa20 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
1aa30 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
1aa40 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
1aa50 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
1aa60 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
1aa70 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
1aa80 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
1aa90 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b   or evaluating [
1aaa0 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65  PRAGMA busy_time
1aab0 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e  out=N] will chan
1aac0 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68  ge the.** busy h
1aad0 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20  andler and thus 
1aae0 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f  clear any previo
1aaf0 75 73 6c 79 20 73 65 74 20 62 75 73 79 20 68 61  usly set busy ha
1ab00 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1ab10 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1ab20 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1ab30 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1ab40 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1ab50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab60 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1ab70 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1ab80 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
1ab90 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  s,.** the busy h
1aba0 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65  andler is not re
1abb0 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75  entrant.  Any su
1abc0 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65  ch actions.** re
1abd0 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
1abe0 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a  d behavior..** .
1abf0 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65  ** A busy handle
1ac00 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  r must not close
1ac10 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ac20 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b  nnection.** or [
1ac30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
1ac40 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  nt] that invoked
1ac50 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ac60 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1ac70 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
1ac80 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79  ALL sqlite3_busy
1ac90 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
1aca0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
1acb0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
1acc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
1acd0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
1ace0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
1acf0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1ad00 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1ad10 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1ad20 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e  ndler | busy han
1ad30 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70  dler] that sleep
1ad40 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69  s.** for a speci
1ad50 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74  fied amount of t
1ad60 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65  ime when a table
1ad70 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68   is locked.  ^Th
1ad80 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c  e handler.** wil
1ad90 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65  l sleep multiple
1ada0 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20   times until at 
1adb0 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1adc0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1add0 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75  ing.** have accu
1ade0 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72  mulated.  ^After
1adf0 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
1ae00 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
1ae10 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20  leeping,.** the 
1ae20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20  handler returns 
1ae30 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b  0 which causes [
1ae40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ae50 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  to return.** [SQ
1ae60 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a  LITE_BUSY]..**.*
1ae70 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
1ae80 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
1ae90 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
1aea0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
1aeb0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
1aec0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
1aed0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
1aee0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1aef0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1af00 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
1af10 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
1af20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
1af30 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
1af40 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
1af50 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
1af60 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
1af70 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1af80 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
1af90 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
1afa0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
1afb0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
1afc0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
1afd0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  d.)^.**.** See a
1afe0 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75  lso:  [PRAGMA bu
1aff0 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53  sy_timeout].*/.S
1b000 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
1b010 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1b020 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1b030 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
1b040 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
1b050 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
1b060 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
1b070 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
1b080 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
1b090 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  3.**.** This is 
1b0a0 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  a legacy interfa
1b0b0 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65  ce that is prese
1b0c0 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rved for backwar
1b0d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
1b0e0 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73  ..** Use of this
1b0f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
1b100 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  t recommended..*
1b110 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a  *.** Definition:
1b120 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62   A <b>result tab
1b130 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79  le</b> is memory
1b140 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20   data structure 
1b150 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a  created by the.*
1b160 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  * [sqlite3_get_t
1b170 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63  able()] interfac
1b180 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62  e.  A result tab
1b190 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a  le records the.*
1b1a0 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79  * complete query
1b1b0 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e   results from on
1b1c0 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65  e or more querie
1b1d0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  s..**.** The tab
1b1e0 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20  le conceptually 
1b1f0 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  has a number of 
1b200 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73  rows and columns
1b210 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20  .  But.** these 
1b220 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20  numbers are not 
1b230 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75  part of the resu
1b240 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e  lt table itself.
1b250 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65    These.** numbe
1b260 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20  rs are obtained 
1b270 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74  separately.  Let
1b280 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   N be the number
1b290 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20   of rows.** and 
1b2a0 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  M be the number 
1b2b0 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a  of columns..**.*
1b2c0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1b2d0 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
1b2e0 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f  pointers to zero
1b2f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1b300 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  8 strings..** Th
1b310 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20  ere are (N+1)*M 
1b320 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  elements in the 
1b330 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73  array.  The firs
1b340 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69  t M pointers poi
1b350 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65  nt.** to zero-te
1b360 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
1b370 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74   that  contain t
1b380 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20  he names of the 
1b390 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20  columns..** The 
1b3a0 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65  remaining entrie
1b3b0 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71  s all point to q
1b3c0 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e  uery results.  N
1b3d0 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c  ULL values resul
1b3e0 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69  t.** in NULL poi
1b3f0 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65  nters.  All othe
1b400 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20  r values are in 
1b410 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f  their UTF-8 zero
1b420 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1b430 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61  tring representa
1b440 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64  tion as returned
1b450 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
1b460 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a  umn_text()]..**.
1b470 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1b480 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20  e might consist 
1b490 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d  of one or more m
1b4a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b4b0 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  s..** It is not 
1b4c0 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72  safe to pass a r
1b4d0 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65  esult table dire
1b4e0 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33  ctly to [sqlite3
1b4f0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72  _free()]..** A r
1b500 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75  esult table shou
1b510 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  ld be deallocate
1b520 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b530 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a  _free_table()]..
1b540 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78  **.** ^(As an ex
1b550 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73  ample of the res
1b560 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74  ult table format
1b570 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72  , suppose a quer
1b580 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61  y result.** is a
1b590 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b5a0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b5b0 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d  e>.**        Nam
1b5c0 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a  e        | Age.*
1b5d0 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d  *        -------
1b5e0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b5f0 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65  .**        Alice
1b600 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20         | 43.**  
1b610 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20        Bob       
1b620 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20    | 28.**       
1b630 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32   Cindy       | 2
1b640 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  1.** </pre></blo
1b650 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1b660 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c  here are two col
1b670 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74  umn (M==2) and t
1b680 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29  hree rows (N==3)
1b690 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72  .  Thus the.** r
1b6a0 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20  esult table has 
1b6b0 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70  8 entries.  Supp
1b6c0 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74  ose the result t
1b6d0 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a  able is stored.*
1b6e0 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61  * in an array na
1b6f0 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54  mes azResult.  T
1b700 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c  hen azResult hol
1b710 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a  ds this content:
1b720 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b730 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20  te><pre>.**     
1b740 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b750 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20  0] = "Name";.** 
1b760 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1b770 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a  #91;1] = "Age";.
1b780 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1b790 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69  lt&#91;2] = "Ali
1b7a0 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ce";.**        a
1b7b0 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d  zResult&#91;3] =
1b7c0 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "43";.**       
1b7d0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d   azResult&#91;4]
1b7e0 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20   = "Bob";.**    
1b7f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b800 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20  ;5] = "28";.**  
1b810 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b820 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b  91;6] = "Cindy";
1b830 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1b840 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31  ult&#91;7] = "21
1b850 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1b860 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1b870 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
1b880 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74  et_table() funct
1b890 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e  ion evaluates on
1b8a0 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d  e or more.** sem
1b8b0 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64  icolon-separated
1b8c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1b8d0 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  in the zero-term
1b8e0 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20  inated UTF-8.** 
1b8f0 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e  string of its 2n
1b900 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
1b910 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74  returns a result
1b920 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a   table to the.**
1b930 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69   pointer given i
1b940 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65  n its 3rd parame
1b950 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  ter..**.** After
1b960 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1b970 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
1b980 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  th the result fr
1b990 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  om sqlite3_get_t
1b9a0 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75  able(),.** it mu
1b9b0 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75  st pass the resu
1b9c0 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72  lt table pointer
1b9d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1b9e0 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65  _table() in orde
1b9f0 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20  r to.** release 
1ba00 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20  the memory that 
1ba10 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42  was malloced.  B
1ba20 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61  ecause of the wa
1ba30 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
1ba40 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70  3_malloc()] happ
1ba50 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74  ens within sqlit
1ba60 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20  e3_get_table(), 
1ba70 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66  the calling.** f
1ba80 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  unction must not
1ba90 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71   try to call [sq
1baa0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69  lite3_free()] di
1bab0 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a  rectly.  Only.**
1bac0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1bad0 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20  able()] is able 
1bae0 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  to release the m
1baf0 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61  emory properly a
1bb00 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a  nd safely..**.**
1bb10 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1bb20 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61  _table() interfa
1bb30 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  ce is implemente
1bb40 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61  d as a wrapper a
1bb50 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  round.** [sqlite
1bb60 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20  3_exec()].  The 
1bb70 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1bb80 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  e() routine does
1bb90 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73   not have access
1bba0 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72  .** to any inter
1bbb0 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75  nal data structu
1bbc0 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  res of SQLite.  
1bbd0 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65  It uses only the
1bbe0 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72   public.** inter
1bbf0 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72  face defined her
1bc00 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75  e.  As a consequ
1bc10 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61  ence, errors tha
1bc20 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a  t occur in the.*
1bc30 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20  * wrapper layer 
1bc40 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69  outside of the i
1bc50 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33  nternal [sqlite3
1bc60 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72  _exec()] call ar
1bc70 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74  e not.** reflect
1bc80 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74  ed in subsequent
1bc90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
1bca0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72  e3_errcode()] or
1bcb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1bcc0 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  msg()]..*/.SQLIT
1bcd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1bce0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1bcf0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
1bd00 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1bd10 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
1bd20 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
1bd30 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1bd40 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
1bd50 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
1bd60 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
1bd70 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
1bd80 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
1bd90 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
1bda0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1bdb0 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
1bdc0 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1bdd0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
1bde0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
1bdf0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
1be00 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
1be10 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
1be20 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
1be30 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
1be40 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
1be50 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c  ITE_API void SQL
1be60 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1be70 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1be80 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1be90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1bea0 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1beb0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1bec0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1bed0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1bee0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1bef0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1bf00 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1bf10 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1bf20 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1bf30 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1bf40 20 75 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74   understand most
1bf50 20 6f 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b   of the common K
1bf60 26 52 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  &R formatting op
1bf70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73  tions,.** plus s
1bf80 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e  ome additional n
1bf90 6f 6e 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d  on-standard form
1bfa0 61 74 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65  ats, detailed be
1bfb0 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  low..** Note tha
1bfc0 74 20 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f  t some of the mo
1bfd0 72 65 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61  re obscure forma
1bfe0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72  tting options fr
1bff0 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c  om recent.** C-l
1c000 69 62 72 61 72 79 20 73 74 61 6e 64 61 72 64 73  ibrary standards
1c010 20 61 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f   are omitted fro
1c020 6d 20 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74  m this implement
1c030 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
1c040 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  e sqlite3_mprint
1c050 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  f() and sqlite3_
1c060 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  vmprintf() routi
1c070 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a  nes write their.
1c080 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20  ** results into 
1c090 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
1c0a0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
1c0b0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  lloc()]..** The 
1c0c0 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
1c0d0 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f   by these two ro
1c0e0 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65  utines should be
1c0f0 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20  .** released by 
1c100 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c110 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65  .  ^Both routine
1c120 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55  s return a.** NU
1c130 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73  LL pointer if [s
1c140 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c150 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1c160 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a  locate enough.**
1c170 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20   memory to hold 
1c180 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
1c190 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ring..**.** ^(Th
1c1a0 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  e sqlite3_snprin
1c1b0 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  tf() routine is 
1c1c0 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72  similar to "snpr
1c1d0 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20  intf()" from.** 
1c1e0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1c1f0 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73  ibrary.  The res
1c200 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69  ult is written i
1c210 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65  nto the.** buffe
1c220 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68  r supplied as th
1c230 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1c240 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73  er whose size is
1c250 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65   given by.** the
1c260 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1c270 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1c280 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20  order of the.** 
1c290 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65  first two parame
1c2a0 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64  ters is reversed
1c2b0 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29   from snprintf()
1c2c0 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a  .)^  This is an.
1c2d0 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63  ** historical ac
1c2e0 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e  cident that cann
1c2f0 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68  ot be fixed with
1c300 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20  out breaking.** 
1c310 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
1c320 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65  ibility.  ^(Note
1c330 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74   also that sqlit
1c340 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1c350 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1c360 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72  er to its buffer
1c370 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1c380 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61  number of.** cha
1c390 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79  racters actually
1c3a0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1c3b0 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20  e buffer.)^  We 
1c3c0 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68  admit that.** th
1c3d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
1c3e0 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77  acters written w
1c3f0 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75  ould be a more u
1c400 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20  seful return.** 
1c410 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e  value but we can
1c420 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69  not change the i
1c430 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1c440 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c450 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f  f().** now witho
1c460 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70  ut breaking comp
1c470 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
1c480 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65   ^As long as the
1c490 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20   buffer size is 
1c4a0 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72  greater than zer
1c4b0 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  o, sqlite3_snpri
1c4c0 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74  ntf().** guarant
1c4d0 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66  ees that the buf
1c4e0 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65  fer is always ze
1c4f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
1c500 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61  ^The first.** pa
1c510 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74  rameter "n" is t
1c520 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66  he total size of
1c530 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63   the buffer, inc
1c540 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72  luding space for
1c550 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72  .** the zero ter
1c560 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65  minator.  So the
1c570 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20   longest string 
1c580 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70  that can be comp
1c590 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65  letely.** writte
1c5a0 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68  n will be n-1 ch
1c5b0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
1c5c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e  ^The sqlite3_vsn
1c5d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1c5e0 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65   is a varargs ve
1c5f0 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  rsion of sqlite3
1c600 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a  _snprintf()..**.
1c610 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1c620 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20  s all implement 
1c630 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20  some additional 
1c640 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70  formatting.** op
1c650 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75  tions that are u
1c660 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72  seful for constr
1c670 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65  ucting SQL state
1c680 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66  ments..** All of
1c690 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74   the usual print
1c6a0 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  f() formatting o
1c6b0 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49  ptions apply.  I
1c6c0 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72  n addition, ther
1c6d0 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22  e.** is are "%q"
1c6e0 2c 20 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64  , "%Q", "%w" and
1c6f0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1c700 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1c710 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1c720 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1c730 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1c740 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1c750 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1c760 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1c770 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1c780 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1c790 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1c7a0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1c7b0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1c7c0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1c7d0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1c7e0 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1c7f0 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1c800 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1c810 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1c820 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1c830 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1c840 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1c850 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1c860 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1c870 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1c880 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c890 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c8a0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1c8b0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1c8c0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1c8d0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1c8e0 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1c8f0 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1c900 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1c910 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c920 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c930 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1c940 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1c950 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1c960 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1c970 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1c980 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1c990 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1c9a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1c9b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1c9c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1c9d0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1c9e0 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1c9f0 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1ca00 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1ca10 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1ca20 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1ca30 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1ca40 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1ca50 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1ca60 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1ca70 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1ca80 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1ca90 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1caa0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cab0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1cac0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1cad0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1cae0 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1caf0 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1cb00 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1cb10 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1cb20 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1cb30 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1cb40 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1cb50 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1cb60 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1cb70 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1cb80 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1cb90 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1cba0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1cbb0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1cbc0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1cbd0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1cbe0 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1cbf0 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1cc00 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1cc10 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1cc20 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1cc30 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1cc40 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1cc50 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1cc60 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1cc70 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1cc80 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1cc90 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1cca0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1ccb0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1ccc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1ccd0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1cce0 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1ccf0 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1cd00 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1cd10 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1cd20 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1cd30 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1cd40 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1cd50 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1cd60 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1cd70 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1cd80 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1cd90 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1cda0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1cdb0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1cdc0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1cdd0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1cde0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1cdf0 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1ce00 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1ce10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1ce20 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1ce30 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1ce40 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1ce50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1ce60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1ce70 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
1ce80 6f 70 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22  option is like "
1ce90 25 71 22 20 65 78 63 65 70 74 20 74 68 61 74 20  %q" except that 
1cea0 69 74 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a  it expects to.**
1ceb0 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69   be contained wi
1cec0 74 68 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74  thin double-quot
1ced0 65 73 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69  es instead of si
1cee0 6e 67 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64  ngle quotes, and
1cef0 20 69 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74   it.** escapes t
1cf00 68 65 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20  he double-quote 
1cf10 63 68 61 72 61 63 74 65 72 20 69 6e 73 74 65 61  character instea
1cf20 64 20 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d  d of the single-
1cf30 71 75 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74  quote.** charact
1cf40 65 72 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20  er.)^  The "%w" 
1cf50 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1cf60 6e 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  n is intended fo
1cf70 72 20 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69  r safely inserti
1cf80 6e 67 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20  ng.** table and 
1cf90 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74  column names int
1cfa0 6f 20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20  o a constructed 
1cfb0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
1cfc0 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20  *.** ^(The "%z" 
1cfd0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1cfe0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73  n works like "%s
1cff0 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a  " but with the.*
1d000 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  * addition that 
1d010 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67  after the string
1d020 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61   has been read a
1d030 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a  nd copied into.*
1d040 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73  * the result, [s
1d050 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69  qlite3_free()] i
1d060 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
1d070 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a  input string.)^.
1d080 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  */.SQLITE_API ch
1d090 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c  ar *SQLITE_CDECL
1d0a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d0b0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1d0c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1d0d0 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
1d0e0 4c 4c 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  LL sqlite3_vmpri
1d0f0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
1d100 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54   va_list);.SQLIT
1d110 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1d120 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
1d130 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1d140 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1d150 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
1d160 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  I char *SQLITE_S
1d170 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76  TDCALL sqlite3_v
1d180 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1d190 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1d1a0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1d1b0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1d1c0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1d1d0 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1d1e0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1d1f0 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1d200 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1d210 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1d220 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1d230 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1d240 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1d250 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1d260 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1d270 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1d280 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1d290 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1d2a0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1d2b0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1d2c0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1d2d0 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1d2e0 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1d2f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1d300 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1d310 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1d320 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1d330 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1d340 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1d350 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1d360 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1d370 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1d380 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1d390 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1d3a0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1d3b0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1d3c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1d3d0 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1d3e0 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1d3f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1d400 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1d410 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1d420 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1d430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1d440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d450 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20  te3_malloc64(N) 
1d460 72 6f 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75  routine works ju
1d470 73 74 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74  st like.** sqlit
1d480 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63  e3_malloc(N) exc
1d490 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e  ept that N is an
1d4a0 20 75 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74   unsigned 64-bit
1d4b0 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64   integer instead
1d4c0 0a 2a 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20  .** of a signed 
1d4d0 33 32 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a  32-bit integer..
1d4e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73  **.** ^Calling s
1d4f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69  qlite3_free() wi
1d500 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65  th a pointer pre
1d510 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
1d520 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  .** by sqlite3_m
1d530 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1d540 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c  e3_realloc() rel
1d550 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72  eases that memor
1d560 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20  y so.** that it 
1d570 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e  might be reused.
1d580 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66    ^The sqlite3_f
1d590 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ree() routine is
1d5a0 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69  .** a no-op if i
1d5b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1d5c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50  NULL pointer.  P
1d5d0 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f  assing a NULL po
1d5e0 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69  inter.** to sqli
1d5f0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61  te3_free() is ha
1d600 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62  rmless.  After b
1d610 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f  eing freed, memo
1d620 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69  ry.** should nei
1d630 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72  ther be read nor
1d640 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20   written.  Even 
1d650 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73  reading previous
1d660 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f  ly freed.** memo
1d670 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ry might result 
1d680 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  in a segmentatio
1d690 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72  n fault or other
1d6a0 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a   severe error..*
1d6b0 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74  * Memory corrupt
1d6c0 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74  ion, a segmentat
1d6d0 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74  ion fault, or ot
1d6e0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1d6f0 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74  .** might result
1d700 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65   if sqlite3_free
1d710 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
1d720 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  h a non-NULL poi
1d730 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73  nter that.** was
1d740 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72   not obtained fr
1d750 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1d760 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1d770 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20  ealloc()..**.** 
1d780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
1d790 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66  lloc(X,N) interf
1d7a0 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1d7b0 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1d7c0 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1d7d0 69 6f 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c  ion X to be at l
1d7e0 65 61 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a  east N bytes..**
1d7f0 20 5e 49 66 20 74 68 65 20 58 20 70 61 72 61 6d   ^If the X param
1d800 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1d810 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20  realloc(X,N).** 
1d820 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1d830 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1d840 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1d850 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1d860 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1d870 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70  ..** ^If the N p
1d880 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1d890 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1d8a0 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1d8b0 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1d8c0 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1d8d0 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1d8e0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1d8f0 74 65 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20  te3_free(X)..** 
1d900 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1d910 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20  (X,N) returns a 
1d920 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1d930 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1d940 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1d950 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1d960 20 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69   NULL if insuffi
1d970 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20  cient memory is 
1d980 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1d990 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1d9a0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d9b0 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1d9c0 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1d9d0 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1d9e0 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1d9f0 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1da00 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1da10 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1da20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1da30 2c 4e 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  ,N) and the prio
1da40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1da50 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1da60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1da70 4e 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20  N) returns NULL 
1da80 61 6e 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76  and N is positiv
1da90 65 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70  e, then the.** p
1daa0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1dab0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1dac0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1dad0 5f 72 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20  _realloc64(X,N) 
1dae0 69 6e 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73  interfaces works
1daf0 20 74 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20   the same as.** 
1db00 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1db10 58 2c 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  X,N) except that
1db20 20 4e 20 69 73 20 61 20 36 34 2d 62 69 74 20 75   N is a 64-bit u
1db30 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
1db40 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20  instead.** of a 
1db50 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
1db60 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  teger..**.** ^If
1db70 20 58 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61   X is a memory a
1db80 6c 6c 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f  llocation previo
1db90 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
1dba0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  om sqlite3_mallo
1dbb0 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  c(),.** sqlite3_
1dbc0 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69  malloc64(), sqli
1dbd0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f  te3_realloc(), o
1dbe0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1dbf0 63 36 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73  c64(), then.** s
1dc00 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1dc10 72 65 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65  returns the size
1dc20 20 6f 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20   of that memory 
1dc30 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79  allocation in by
1dc40 74 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  tes..** ^The val
1dc50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
1dc60 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
1dc70 6d 69 67 68 74 20 62 65 20 6c 61 72 67 65 72 20  might be larger 
1dc80 74 68 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a  than the number.
1dc90 2a 2a 20 6f 66 20 62 79 74 65 73 20 72 65 71 75  ** of bytes requ
1dca0 65 73 74 65 64 20 77 68 65 6e 20 58 20 77 61 73  ested when X was
1dcb0 20 61 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66   allocated.  ^If
1dcc0 20 58 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   X is a NULL poi
1dcd0 6e 74 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  nter then.** sql
1dce0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1dcf0 74 75 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20  turns zero.  If 
1dd00 58 20 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65  X points to some
1dd10 74 68 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f  thing that is no
1dd20 74 0a 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69  t.** the beginni
1dd30 6e 67 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  ng of memory all
1dd40 6f 63 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69  ocation, or if i
1dd50 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f  t points to a fo
1dd60 72 6d 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20  rmerly.** valid 
1dd70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1dd80 6e 20 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62  n that has now b
1dd90 65 65 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20  een freed, then 
1dda0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
1ddb0 6f 66 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  of sqlite3_msize
1ddc0 28 58 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  (X) is undefined
1ddd0 20 61 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61   and possibly ha
1dde0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rmful..**.** ^Th
1ddf0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1de00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1de10 6c 6f 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  loc(), sqlite3_r
1de20 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c  ealloc(),.** sql
1de30 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c  ite3_malloc64(),
1de40 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1de50 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61  lloc64().** is a
1de60 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1de70 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1de80 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1de90 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1dea0 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1deb0 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1dec0 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1ded0 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1dee0 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1def0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1df00 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1df10 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1df20 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1df30 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1df40 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1df50 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1df60 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1df70 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1df80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1df90 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1dfa0 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1dfb0 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1dfc0 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1dfd0 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1dfe0 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1dff0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1e000 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1e010 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1e020 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1e030 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1e040 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1e050 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1e060 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1e070 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1e080 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1e090 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1e0a0 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1e0b0 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1e0c0 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1e0d0 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1e0e0 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1e0f0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1e100 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1e110 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1e120 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1e130 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1e140 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1e150 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1e160 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1e170 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1e180 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1e190 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1e1a0 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1e1b0 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1e1c0 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1e1d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1e1e0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1e1f0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1e200 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1e210 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1e220 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1e230 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1e240 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1e250 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1e260 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1e270 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1e280 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1e290 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1e2a0 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1e2b0 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1e2c0 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1e2d0 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1e2e0 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1e2f0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1e300 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1e310 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e320 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1e330 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
1e340 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61  DCALL sqlite3_ma
1e350 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54  lloc(int);.SQLIT
1e360 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
1e370 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1e380 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1e390 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
1e3a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
1e3b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
1e3c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
1e3d0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
1e3e0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
1e3f0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1e400 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
1e410 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
1e420 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
1e430 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41  oid SQLITE_STDCA
1e440 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  LL sqlite3_free(
1e450 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
1e460 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  PI sqlite3_uint6
1e470 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
1e480 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76   sqlite3_msize(v
1e490 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1e4a0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e4b0 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74  llocator Statist
1e4c0 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ics.**.** SQLite
1e4d0 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20   provides these 
1e4e0 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66  two interfaces f
1e4f0 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20  or reporting on 
1e500 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66  the status.** of
1e510 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61   the [sqlite3_ma
1e520 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  lloc()], [sqlite
1e530 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b  3_free()], and [
1e540 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e550 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20  )].** routines, 
1e560 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62  which form the b
1e570 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1e580 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
1e590 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tem..**.** ^The 
1e5a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1e5b0 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20  used()] routine 
1e5c0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1e5d0 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f  er of bytes.** o
1e5e0 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74  f memory current
1e5f0 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28  ly outstanding (
1e600 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74  malloced but not
1e610 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65   freed)..** ^The
1e620 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e630 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f  _highwater()] ro
1e640 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
1e650 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c  e maximum.** val
1e660 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  ue of [sqlite3_m
1e670 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69  emory_used()] si
1e680 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74  nce the high-wat
1e690 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c  er mark.** was l
1e6a0 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65  ast reset.  ^The
1e6b0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1e6c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1e6d0 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ory_used()] and.
1e6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e6f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e700 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72  include any over
1e710 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79  head.** added by
1e720 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69   SQLite in its i
1e730 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1e740 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e750 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20  ()],.** but not 
1e760 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62  overhead added b
1e770 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c  y the any underl
1e780 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72  ying system libr
1e790 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ary.** routines 
1e7a0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61  that [sqlite3_ma
1e7b0 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c  lloc()] may call
1e7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1e7d0 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d  ory high-water m
1e7e0 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20  ark is reset to 
1e7f0 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
1e800 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  e of.** [sqlite3
1e810 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1e820 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  if and only if t
1e830 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  he parameter to.
1e840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1e850 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1e860 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76  is true.  ^The v
1e870 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1e880 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   by [sqlite3_mem
1e890 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29  ory_highwater(1)
1e8a0 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61  ] is the high-wa
1e8b0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f  ter mark.** prio
1e8c0 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a  r to the reset..
1e8d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
1e8e0 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
1e8f0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1e900 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e910 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
1e920 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53   sqlite3_int64 S
1e930 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1e940 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1e950 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74  hwater(int reset
1e960 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Flag);../*.** CA
1e970 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52  PI3REF: Pseudo-R
1e980 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e  andom Number Gen
1e990 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c  erator.**.** SQL
1e9a0 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68  ite contains a h
1e9b0 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75  igh-quality pseu
1e9c0 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72  do-random number
1e9d0 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47   generator (PRNG
1e9e0 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c  ) used to.** sel
1e9f0 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49  ect random [ROWI
1ea00 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e  D | ROWIDs] when
1ea10 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72   inserting new r
1ea20 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61  ecords into a ta
1ea30 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65  ble that.** alre
1ea40 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72  ady uses the lar
1ea50 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52  gest possible [R
1ea60 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47  OWID].  The PRNG
1ea70 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f   is also used fo
1ea80 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69  r.** the build-i
1ea90 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72  n random() and r
1eaa0 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20  andomblob() SQL 
1eab0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73  functions.  This
1eac0 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77   interface allow
1ead0 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  s.** application
1eae0 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
1eaf0 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74  same PRNG for ot
1eb00 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a  her purposes..**
1eb10 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74  .** ^A call to t
1eb20 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72  his routine stor
1eb30 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61  es N bytes of ra
1eb40 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75  ndomness into bu
1eb50 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20  ffer P..** ^The 
1eb60 50 20 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20  P parameter can 
1eb70 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1eb80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69  r..**.** ^If thi
1eb90 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f  s routine has no
1eba0 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c  t been previousl
1ebb0 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74  y called or if t
1ebc0 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63  he previous.** c
1ebd0 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74  all had N less t
1ebe0 68 61 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c  han one or a NUL
1ebf0 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c  L pointer for P,
1ec00 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1ec10 73 0a 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e  s.** seeded usin
1ec20 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
1ec30 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1ec40 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1ec50 64 20 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61  d of.** the defa
1ec60 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
1ec70 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66  ] object..** ^If
1ec80 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
1ec90 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1eca0 6e 65 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31  ne had an N of 1
1ecb0 20 6f 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a   or more and a.*
1ecc0 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65  * non-NULL P the
1ecd0 6e 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e  n the pseudo-ran
1ece0 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72  domness is gener
1ecf0 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c  ated.** internal
1ed00 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72  ly and without r
1ed10 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b  ecourse to the [
1ed20 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61  sqlite3_vfs] xRa
1ed30 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68  ndomness.** meth
1ed40 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  od..*/.SQLITE_AP
1ed50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
1ed60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61  DCALL sqlite3_ra
1ed70 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1ed80 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1ed90 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1eda0 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1edb0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1edc0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1edd0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1ede0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1edf0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1ee00 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1ee10 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1ee20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1ee30 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1ee40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1ee50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^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 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1ee80 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1ee90 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1eea0 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1eeb0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1eec0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1eed0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1eee0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1eef0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1ef00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ef10 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1ef20 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1ef30 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1ef40 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1ef50 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1ef60 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1ef70 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1ef80 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1ef90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1efa0 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1efb0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1efc0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1efd0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1efe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1eff0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1f000 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1f010 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1f020 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1f030 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1f040 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1f050 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1f060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1f070 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1f080 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1f090 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1f0a0 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1f0b0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1f0c0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1f0d0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1f0e0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1f0f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1f100 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1f110 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1f120 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1f130 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1f140 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1f150 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1f160 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f170 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1f180 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1f190 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1f1a0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1f1b0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1f1c0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1f1d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1f1e0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1f1f0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1f200 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1f210 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1f220 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1f230 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1f240 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1f250 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1f260 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1f270 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1f280 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1f290 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1f2a0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1f2b0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1f2c0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1f2d0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1f2e0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1f2f0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1f300 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1f310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1f320 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1f330 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1f340 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1f350 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1f360 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1f370 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1f380 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1f390 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1f3a0 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1f3b0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1f3c0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1f3d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1f3e0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1f3f0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1f400 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1f410 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1f420 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1f430 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f440 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1f450 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1f460 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1f470 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1f480 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1f490 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1f4a0 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1f4b0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1f4c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1f4d0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1f4e0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1f4f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1f500 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1f510 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1f520 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1f530 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1f540 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1f550 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1f560 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1f570 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1f580 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1f590 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1f5a0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1f5b0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1f5c0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1f5d0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1f5e0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1f5f0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1f600 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1f610 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1f620 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1f630 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1f640 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1f650 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1f660 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1f670 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1f680 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1f690 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1f6a0 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1f6b0 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1f6c0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1f6d0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1f6e0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1f6f0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1f700 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1f710 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1f720 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1f730 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1f740 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1f750 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1f760 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1f770 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1f780 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1f790 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1f7a0 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1f7b0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1f7c0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1f7d0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1f7e0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1f7f0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1f800 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1f810 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1f820 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1f830 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1f840 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1f850 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1f860 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1f870 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1f880 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1f890 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1f8a0 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1f8b0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1f8c0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1f8d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1f8e0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1f8f0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1f900 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1f910 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1f920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f930 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1f940 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1f950 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1f960 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1f970 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1f980 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1f990 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1f9a0 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1f9b0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1f9c0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1f9d0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1f9e0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1f9f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1fa00 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1fa10 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1fa20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1fa30 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1fa40 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1fa50 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1fa60 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1fa70 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1fa80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1fa90 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1faa0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1fab0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1fac0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1fad0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1fae0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1faf0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1fb00 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1fb10 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1fb20 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1fb30 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1fb40 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1fb50 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1fb60 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1fb70 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1fb80 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1fb90 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1fba0 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1fbb0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1fbc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1fbd0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1fbe0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1fbf0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1fc00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1fc10 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1fc20 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1fc30 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1fc40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1fc50 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1fc60 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1fc70 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1fc80 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1fc90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1fca0 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1fcb0 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1fcc0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1fcd0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1fce0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1fcf0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1fd00 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1fd10 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1fd20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1fd30 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1fd40 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1fd50 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1fd60 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1fd70 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1fd80 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1fd90 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1fda0 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1fdb0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fdc0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1fdd0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1fde0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1fdf0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1fe00 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1fe10 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1fe20 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1fe30 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1fe40 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1fe50 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1fe60 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1fe70 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1fe80 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1fe90 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1fea0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1feb0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1fec0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1fed0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1fee0 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
1fef0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1ff00 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
1ff10 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
1ff20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
1ff30 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
1ff40 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
1ff50 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1ff60 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1ff70 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
1ff80 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
1ff90 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
1ffa0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
1ffb0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
1ffc0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1ffd0 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
1ffe0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
1fff0 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
20000 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
20010 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
20020 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
20030 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
20040 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
20050 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
20060 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
20070 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
20080 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
20090 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
200a0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
200b0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
200c0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
200d0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
200e0 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
200f0 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
20100 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
20110 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
20120 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
20130 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
20140 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
20150 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
20160 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
20170 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
20180 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
20190 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
201a0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
201b0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
201c0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
201d0 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
201e0 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
201f0 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
20200 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20210 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
20220 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
20230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20240 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
20250 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
20260 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20270 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
20280 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
20290 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
202a0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
202b0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
202c0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
202d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
202e0 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
202f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
20300 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
20310 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
20320 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
20330 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
20340 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
20350 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20360 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
20370 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
20380 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
20390 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
203a0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
203b0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
203c0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
203d0 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
203e0 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
203f0 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
20400 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
20410 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
20420 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
20430 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
20440 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
20450 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
20460 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
20470 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
20480 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
20490 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
204a0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
204b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
204c0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
204d0 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
204e0 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
204f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
20500 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20510 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
20520 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
20530 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
20540 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
20550 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
20560 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
20570 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
20580 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
20590 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
205a0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
205b0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
205c0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
205d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
205e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
205f0 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
20600 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
20610 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
20620 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
20630 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
20640 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
20650 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20660 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20670 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
20680 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
20690 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
206a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
206b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
206c0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
206d0 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
206e0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
206f0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
20700 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
20710 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
20720 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
20730 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
20740 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20750 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
20760 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
20770 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
20780 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
20790 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
207a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
207b0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
207c0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
207d0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
207e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
207f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
20800 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
20810 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
20820 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
20830 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20840 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
20850 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
20860 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
20870 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20880 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20890 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
208a0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
208b0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
208c0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
208d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
208e0 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
208f0 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
20900 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
20910 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20920 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20930 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
20940 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
20950 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20960 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20970 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20980 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
20990 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
209a0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
209b0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
209c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
209d0 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
209e0 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
209f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20a00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20a10 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20a20 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
20a30 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
20a40 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20a50 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20a60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20a70 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
20a80 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
20a90 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20aa0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20ac0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
20ad0 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
20ae0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
20af0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
20b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
20b10 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
20b20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
20b30 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
20b40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
20b50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
20b60 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
20b70 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
20b80 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
20b90 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
20bb0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
20bc0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
20bd0 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
20be0 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
20bf0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
20c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20c10 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
20c20 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
20c30 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
20c40 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
20c50 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
20c60 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
20c70 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
20c80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20c90 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
20ca0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
20cb0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
20cc0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20cd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20ce0 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
20cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
20d00 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
20d10 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
20d20 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
20d30 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
20d40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
20d50 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
20d60 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
20d70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20d80 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
20d90 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
20da0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
20db0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
20dc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20dd0 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
20de0 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
20df0 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
20e00 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
20e10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
20e20 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
20e30 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
20e40 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20e50 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20e60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20e70 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
20e80 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
20e90 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20ea0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20eb0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20ec0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
20ed0 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
20ee0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
20ef0 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
20f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
20f10 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
20f20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
20f30 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
20f40 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
20f50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20f60 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
20f70 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
20f80 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
20f90 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
20fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20fb0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
20fc0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
20fd0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
20fe0 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
20ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21000 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
21010 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
21020 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
21030 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
21040 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
21050 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
21060 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
21070 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
21080 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
21090 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
210a0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
210b0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
210c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
210d0 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63  tines register c
210e0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
210f0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73  s that can be us
21100 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e  ed for.** tracin
21110 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20  g and profiling 
21120 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  the execution of
21130 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
21140 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
21150 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
21160 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
21170 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69  te3_trace() is i
21180 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72  nvoked at.** var
21190 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20  ious times when 
211a0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
211b0 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79   is being run by
211c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
211d0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
211e0 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
211f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
21200 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64  ith a UTF-8 rend
21210 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20  ering of the.** 
21220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  SQL statement te
21230 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d  xt as the statem
21240 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73  ent first begins
21250 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e   executing..** ^
21260 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69  (Additional sqli
21270 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21280 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75  backs might occu
21290 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69  r.** as each tri
212a0 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61  ggered subprogra
212b0 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54  m is entered.  T
212c0 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72  he callbacks for
212d0 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e   triggers.** con
212e0 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c  tain a UTF-8 SQL
212f0 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64   comment that id
21300 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69  entifies the tri
21310 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  gger.)^.**.** Th
21320 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
21330 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
21340 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
21350 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c  can be used to l
21360 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67  imit.** the leng
21370 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72  th of [bound par
21380 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f  ameter] expansio
21390 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20  n in the output 
213a0 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  of sqlite3_trace
213b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  ()..**.** ^The c
213c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
213d0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
213e0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
213f0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
21400 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
21410 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
21420 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
21430 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
21440 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
21450 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
21460 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
21470 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
21480 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
21490 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
214a0 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
214b0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
214c0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
214d0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
214e0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
214f0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
21500 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
21510 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
21520 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
21530 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
21540 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
21550 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
21560 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
21570 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
21580 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21590 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
215a0 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
215b0 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
215c0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
215d0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
215e0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
215f0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
21600 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
21610 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
21620 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
21630 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
21640 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53   of SQLite..*/.S
21650 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
21660 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
21670 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
21680 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
21690 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
216a0 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
216b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
216c0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
216d0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
216e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f  CALL sqlite3_pro
216f0 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
21700 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
21710 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
21720 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
21730 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
21740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
21750 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
21760 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
21770 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
21780 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
21790 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
217a0 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
217b0 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
217c0 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
217d0 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
217e0 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
217f0 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
21800 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
21810 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
21820 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
21830 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
21840 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
21850 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
21860 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
21870 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
21880 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
21890 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
218a0 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
218b0 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
218c0 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
218d0 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
218e0 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
218f0 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
21900 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
21910 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
21920 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
21930 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
21940 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
21950 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
21960 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
21970 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
21980 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
21990 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
219a0 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
219b0 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
219c0 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
219d0 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
219e0 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
219f0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
21a00 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
21a10 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
21a20 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
21a30 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
21a40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21a50 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
21a60 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
21a70 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
21a80 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
21a90 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
21aa0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
21ab0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
21ac0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
21ad0 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
21ae0 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
21af0 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
21b00 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
21b10 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
21b20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
21b30 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
21b40 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
21b50 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
21b60 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
21b70 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
21b80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
21b90 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
21ba0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
21bb0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
21bc0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
21bd0 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
21be0 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
21bf0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
21c00 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
21c10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
21c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21c30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
21c40 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
21c50 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
21c60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21c70 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
21c80 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
21c90 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
21ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21cb0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
21cc0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
21cd0 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
21ce0 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
21cf0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
21d00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
21d10 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
21d20 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
21d30 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
21d40 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
21d50 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
21d60 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
21d70 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43   Connection.** C
21d80 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  ONSTRUCTOR: sqli
21d90 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
21da0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
21db0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
21dc0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
21dd0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
21de0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21df0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
21e00 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
21e10 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
21e20 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21e30 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21e40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
21e50 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
21e60 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
21e70 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
21e80 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
21e90 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
21ea0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
21eb0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
21ec0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
21ed0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
21ee0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
21ef0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
21f00 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
21f10 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
21f20 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
21f30 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
21f40 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
21f50 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
21f60 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
21f70 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
21f80 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
21f90 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
21fa0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
21fb0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
21fc0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
21fd0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
21fe0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
21ff0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
22000 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
22010 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
22020 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
22030 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
22040 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
22050 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
22060 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
22070 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
22080 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
22090 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
220a0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
220b0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
220c0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
220d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
220e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
220f0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
22100 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54  oding will be UT
22110 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61 73 65  F-8 for database
22120 73 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a  s created using.
22130 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
22140 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
22150 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65  n_v2().  ^The de
22160 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
22170 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20  or databases.** 
22180 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 73 71  created using sq
22190 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77  lite3_open16() w
221a0 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e  ill be UTF-16 in
221b0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
221c0 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68   order..**.** Wh
221d0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20  ether or not an 
221e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65  error occurs whe
221f0 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20  n it is opened, 
22200 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73  resources.** ass
22210 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
22220 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22230 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68  ction] handle sh
22240 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64  ould be released
22250 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69   by.** passing i
22260 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  t to [sqlite3_cl
22270 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69  ose()] when it i
22280 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75  s no longer requ
22290 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ired..**.** The 
222a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
222b0 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b  ) interface work
222c0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f  s like sqlite3_o
222d0 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20  pen().** except 
222e0 74 68 61 74 20 69 74 20 61 63 63 65 70 74 73 20  that it accepts 
222f0 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70  two additional p
22300 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64  arameters for ad
22310 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c  ditional control
22320 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77  .** over the new
22330 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22340 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61  tion.  ^(The fla
22350 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  gs parameter to.
22360 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  ** sqlite3_open_
22370 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e  v2() can take on
22380 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
22390 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75  owing three valu
223a0 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  es, optionally c
223b0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74 68 65  ombined with the
223c0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45   .** [SQLITE_OPE
223d0 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  N_NOMUTEX], [SQL
223e0 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
223f0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
22400 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a  N_SHAREDCACHE],.
22410 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
22420 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61  PRIVATECACHE], a
22430 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  nd/or [SQLITE_OP
22440 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e  EN_URI] flags:)^
22450 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e  .**.** <dl>.** ^
22460 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
22470 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e  N_READONLY]</dt>
22480 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22490 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69  base is opened i
224a0 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65  n read-only mode
224b0 2e 20 20 49 66 20 74 68 65 20 64 61 74 61 62 61  .  If the databa
224c0 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61  se does not.** a
224d0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e  lready exist, an
224e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
224f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
22500 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
22510 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f  PEN_READWRITE]</
22520 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
22530 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22540 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
22550 64 20 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73  d writing if pos
22560 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e  sible, or readin
22570 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65  g.** only if the
22580 20 66 69 6c 65 20 69 73 20 77 72 69 74 65 20 70   file is write p
22590 72 6f 74 65 63 74 65 64 20 62 79 20 74 68 65 20  rotected by the 
225a0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
225b0 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20  .  In either.** 
225c0 63 61 73 65 20 74 68 65 20 64 61 74 61 62 61 73  case the databas
225d0 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65  e must already e
225e0 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20  xist, otherwise 
225f0 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
22600 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
22610 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
22620 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
22630 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   | [SQLITE_OPEN_
22640 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  CREATE]</dt>.** 
22650 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
22660 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
22670 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
22680 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74  ng, and is creat
22690 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73  ed if.** it does
226a0 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69   not already exi
226b0 73 74 2e 20 54 68 69 73 20 69 73 20 74 68 65 20  st. This is the 
226c0 62 65 68 61 76 69 6f 72 20 74 68 61 74 20 69 73  behavior that is
226d0 20 61 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72   always used for
226e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
226f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
22700 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a  pen16().</dd>)^.
22710 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </dl>.**.** I
22720 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
22730 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22740 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  pen_v2() is not 
22750 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  one of the.** co
22760 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e  mbinations shown
22770 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c   above optionall
22780 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20  y combined with 
22790 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  other.** [SQLITE
227a0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c  _OPEN_READONLY |
227b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62   SQLITE_OPEN_* b
227c0 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  its].** then the
227d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
227e0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  efined..**.** ^I
227f0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
22800 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67  EN_NOMUTEX] flag
22810 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68   is set, then th
22820 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22830 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69  ction.** opens i
22840 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65  n the multi-thre
22850 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
22860 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  de] as long as t
22870 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  he single-thread
22880 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74  .** mode has not
22890 20 62 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d   been set at com
228a0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
228b0 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68  rt-time.  ^If th
228c0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
228d0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61  N_FULLMUTEX] fla
228e0 67 20 69 73 20 73 65 74 20 74 68 65 6e 20 74 68  g is set then th
228f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22900 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69  ction opens.** i
22910 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
22920 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
22930 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d  ] unless single-
22940 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72  thread was.** pr
22950 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65  eviously selecte
22960 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  d at compile-tim
22970 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22980 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
22990 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
229a0 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74  E] flag causes t
229b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
229c0 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  ection to be.** 
229d0 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20  eligible to use 
229e0 5b 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f  [shared cache mo
229f0 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20  de], regardless 
22a00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
22a10 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68  t shared.** cach
22a20 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69  e is enabled usi
22a30 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  ng [sqlite3_enab
22a40 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
22a50 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51  )].  ^The.** [SQ
22a60 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22a70 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  ECACHE] flag cau
22a80 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
22a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e   connection to n
22aa0 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74  ot.** participat
22ab0 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63  e in [shared cac
22ac0 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66  he mode] even if
22ad0 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a   it is enabled..
22ae0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
22af0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
22b00 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
22b10 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
22b20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
22b30 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  vfs] object that
22b40 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65   defines the ope
22b50 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
22b60 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20  terface that.** 
22b70 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
22b80 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75   connection shou
22b90 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65  ld use.  ^If the
22ba0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
22bb0 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  r is.** a NULL p
22bc0 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20  ointer then the 
22bd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
22be0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20  _vfs] object is 
22bf0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  used..**.** ^If 
22c00 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22c10 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e  ":memory:", then
22c20 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
22c30 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20  orary in-memory 
22c40 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63  database.** is c
22c50 72 65 61 74 65 64 20 66 6f 72 20 74 68 65 20 63  reated for the c
22c60 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69  onnection.  ^Thi
22c70 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61  s in-memory data
22c80 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68  base will vanish
22c90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74   when.** the dat
22ca0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22cb0 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74   is closed.  Fut
22cc0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
22cd0 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20  SQLite might.** 
22ce0 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69  make use of addi
22cf0 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66  tional special f
22d00 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65  ilenames that be
22d10 67 69 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22  gin with the ":"
22d20 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49   character..** I
22d30 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
22d40 20 74 68 61 74 20 77 68 65 6e 20 61 20 64 61 74   that when a dat
22d50 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61  abase filename a
22d60 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67  ctually does beg
22d70 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22  in with.** a ":"
22d80 20 63 68 61 72 61 63 74 65 72 20 79 6f 75 20 73   character you s
22d90 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74 68 65  hould prefix the
22da0 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61   filename with a
22db0 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61   pathname such a
22dc0 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f  s.** "./" to avo
22dd0 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a  id ambiguity..**
22de0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22df0 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79  name is an empty
22e00 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20   string, then a 
22e10 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
22e20 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61  ry.** on-disk da
22e30 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63  tabase will be c
22e40 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70  reated.  ^This p
22e50 72 69 76 61 74 65 20 64 61 74 61 62 61 73 65 20  rivate database 
22e60 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d  will be.** autom
22e70 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
22e80 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20   as soon as the 
22e90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22ea0 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a  ion is closed..*
22eb0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
22ec0 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f  ames in sqlite3_
22ed0 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49  open()]] <h3>URI
22ee0 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a   Filenames</h3>.
22ef0 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66  **.** ^If [URI f
22f00 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72  ilename] interpr
22f10 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
22f20 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65  ed, and the file
22f30 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
22f40 20 62 65 67 69 6e 73 20 77 69 74 68 20 22 66 69   begins with "fi
22f50 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66  le:", then the f
22f60 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72  ilename is inter
22f70 70 72 65 74 65 64 20 61 73 20 61 20 55 52 49 2e  preted as a URI.
22f80 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d   ^URI.** filenam
22f90 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
22fa0 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74   is enabled if t
22fb0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
22fc0 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20  URI] flag is.** 
22fd0 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74  set in the fourt
22fe0 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
22ff0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c  lite3_open_v2(),
23000 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a   or if it has.**
23010 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c   been enabled gl
23020 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65  obally using the
23030 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
23040 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68  URI] option with
23050 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
23060 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f  _config()] metho
23070 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c  d or by the [SQL
23080 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d  ITE_USE_URI] com
23090 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
230a0 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74  ..** As of SQLit
230b0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
230c0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e   URI filename in
230d0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
230e0 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79  turned off.** by
230f0 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75   default, but fu
23100 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
23110 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e   SQLite might en
23120 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d  able URI filenam
23130 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74  e.** interpretat
23140 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20  ion by default. 
23150 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e   See "[URI filen
23160 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74  ames]" for addit
23170 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
23180 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  tion..**.** URI 
23190 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61  filenames are pa
231a0 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74  rsed according t
231b0 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20  o RFC 3986. ^If 
231c0 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73  the URI contains
231d0 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79   an.** authority
231e0 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
231f0 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74  e either an empt
23200 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20  y string or the 
23210 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61  string .** "loca
23220 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20  lhost". ^If the 
23230 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74  authority is not
23240 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
23250 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c   or "localhost",
23260 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73   an .** error is
23270 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65   returned to the
23280 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72   caller. ^The fr
23290 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74  agment component
232a0 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a   of a URI, if .*
232b0 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67  * present, is ig
232c0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  nored..**.** ^SQ
232d0 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 70 61  Lite uses the pa
232e0 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  th component of 
232f0 74 68 65 20 55 52 49 20 61 73 20 74 68 65 20 6e  the URI as the n
23300 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  ame of the disk 
23310 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f  file.** which co
23320 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 61 62  ntains the datab
23330 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ase. ^If the pat
23340 68 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  h begins with a 
23350 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a  '/' character, .
23360 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e  ** then it is in
23370 74 65 72 70 72 65 74 65 64 20 61 73 20 61 6e 20  terpreted as an 
23380 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e  absolute path. ^
23390 49 66 20 74 68 65 20 70 61 74 68 20 64 6f 65 73  If the path does
233a0 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77   not begin .** w
233b0 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69  ith a '/' (meani
233c0 6e 67 20 74 68 61 74 20 74 68 65 20 61 75 74 68  ng that the auth
233d0 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73  ority section is
233e0 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68   omitted from th
233f0 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74  e URI).** then t
23400 68 65 20 70 61 74 68 20 69 73 20 69 6e 74 65 72  he path is inter
23410 70 72 65 74 65 64 20 61 73 20 61 20 72 65 6c 61  preted as a rela
23420 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e  tive path. .** ^
23430 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65  (On windows, the
23440 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74   first component
23450 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   of an absolute 
23460 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72  path .** is a dr
23470 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69 6f  ive specificatio
23480 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e  n (e.g. "C:").)^
23490 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52  .**.** [[core UR
234a0 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  I query paramete
234b0 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72  rs]].** The quer
234c0 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
234d0 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e   URI may contain
234e0 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74   parameters that
234f0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23500 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51  .** either by SQ
23510 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20  Lite itself, or 
23520 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74  by a [VFS | cust
23530 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  om VFS implement
23540 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74  ation]..** SQLit
23550 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d  e and its built-
23560 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72  in [VFSes] inter
23570 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c  pret the.** foll
23580 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61 72 61  owing query para
23590 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
235a0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
235b0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
235c0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
235d0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
235e0 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
235f0 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
23600 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
23610 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
23620 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
23630 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
23640 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
23650 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
23660 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
23670 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
23680 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
23690 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
236a0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
236b0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
236c0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
236d0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
236e0 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
236f0 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
23700 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
23710 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
23720 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
23730 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
23740 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
23750 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
23760 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
23770 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
23780 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
23790 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
237a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
237b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
237c0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
237d0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
237e0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
237f0 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
23800 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
23810 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
23820 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
23830 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
23840 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
23850 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
23860 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
23870 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
23880 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
23890 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
238a0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
238b0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
238c0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
238d0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
238e0 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
238f0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
23900 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
23910 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23920 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
23930 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
23940 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
23950 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
23960 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
23970 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
23980 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
23990 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
239a0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
239b0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
239c0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
239d0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
239e0 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
239f0 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
23a00 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
23a10 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
23a20 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23a30 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
23a40 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
23a50 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
23a60 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
23a70 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
23a80 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
23a90 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
23aa0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
23ab0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
23ac0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
23ad0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
23ae0 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
23af0 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
23b00 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
23b10 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
23b20 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
23b30 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
23b40 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
23b50 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
23b60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
23b70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23b80 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
23b90 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
23ba0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
23bb0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
23bc0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
23bd0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
23be0 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
23bf0 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
23c00 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
23c10 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
23c20 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
23c30 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
23c40 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
23c50 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
23c60 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
23c70 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
23c80 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
23c90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
23ca0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
23cb0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
23cc0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
23cd0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23ce0 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
23cf0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
23d00 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
23d10 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
23d20 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
23d30 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
23d40 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
23d50 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
23d60 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72  s any behavior r
23d70 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
23d80 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
23d90 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23da0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
23db0 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
23dc0 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  lag..**.**  <li>
23dd0 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54   <b>psow</b>: ^T
23de0 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65  he psow paramete
23df0 72 20 69 6e 64 69 63 61 74 65 73 20 77 68 65 74  r indicates whet
23e00 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a  her or not the.*
23e10 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65  *     [powersafe
23e20 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70   overwrite] prop
23e30 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65  erty does or doe
23e40 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74  s not apply to t
23e50 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67  he.**     storag
23e60 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68  e media on which
23e70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23e80 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a  le resides..**.*
23e90 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63  *  <li> <b>noloc
23ea0 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f  k</b>: ^The nolo
23eb0 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
23ec0 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20  a boolean query 
23ed0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20  parameter.**    
23ee0 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69   which if set di
23ef0 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b  sables file lock
23f00 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20  ing in rollback 
23f10 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20  journal modes.  
23f20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75  This.**     is u
23f30 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73  seful for access
23f40 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f  ing a database o
23f50 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74  n a filesystem t
23f60 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  hat does not.** 
23f70 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b      support lock
23f80 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20  ing.  Caution:  
23f90 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  Database corrupt
23fa0 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ion might result
23fb0 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f   if two.**     o
23fc0 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73  r more processes
23fd0 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61   write to the sa
23fe0 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  me database and 
23ff0 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65  any one of those
24000 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65  .**     processe
24010 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e  s uses nolock=1.
24020 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e  .**.**  <li> <b>
24030 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e  immutable</b>: ^
24040 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61  The immutable pa
24050 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f  rameter is a boo
24060 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20  lean query.**   
24070 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74    parameter that
24080 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
24090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
240a0 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a  e is stored on.*
240b0 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
240c0 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d  media.  ^When im
240d0 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20  mutable is set, 
240e0 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
240f0 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64  hat the.**     d
24100 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e  atabase file can
24110 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20  not be changed, 
24120 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73  even by a proces
24130 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a  s with higher.**
24140 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20       privilege, 
24150 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62  and so the datab
24160 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65  ase is opened re
24170 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20  ad-only and all 
24180 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61  locking.**     a
24190 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74  nd change detect
241a0 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ion is disabled.
241b0 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69    Caution: Setti
241c0 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65  ng the immutable
241d0 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79  .**     property
241e0 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66   on a database f
241f0 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e  ile that does in
24200 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e   fact change can
24210 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69   result.**     i
24220 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72  n incorrect quer
24230 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72  y results and/or
24240 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
24250 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20  ] errors..**    
24260 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49   See also: [SQLI
24270 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42  TE_IOCAP_IMMUTAB
24280 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a  LE]..**       .*
24290 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
242a0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
242b0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
242c0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
242d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
242e0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
242f0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
24300 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
24310 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
24320 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
24330 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
24340 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
24350 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
24360 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
24370 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
24380 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
24390 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
243a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
243b0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
243c0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
243d0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
243e0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
243f0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
24400 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
24410 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
24420 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
24430 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24440 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
24450 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24460 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24470 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24480 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
24490 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
244a0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
244b0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
244c0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
244d0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
244e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
244f0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
24500 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24510 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
24520 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24530 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
24540 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24550 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
24560 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
24570 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24580 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24590 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
245a0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
245b0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
245c0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
245d0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
245e0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
245f0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
24600 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
24610 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
24620 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
24630 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
24640 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
24650 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
24660 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
24670 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
24680 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
24690 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
246a0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
246b0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
246c0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
246d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
246e0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
246f0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
24700 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
24710 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
24720 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
24730 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
24740 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
24750 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
24760 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
24770 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
24780 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
24790 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
247a0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
247b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
247c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
247d0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
247e0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
247f0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
24800 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
24810 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
24820 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
24830 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
24840 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
24850 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a  x-dotfile <td>.*
24860 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
24870 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24880 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
24890 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
248a0 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a  unix-dotfile".**
248b0 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75            that u
248c0 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e  ses dot-files in
248d0 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20   place of posix 
248e0 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67  advisory locking
248f0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
24900 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
24910 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a  readonly <td> .*
24920 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24930 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20  ror. "readonly" 
24940 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f  is not a valid o
24950 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d  ption for the "m
24960 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a  ode" parameter..
24970 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a  ** </table>.**.*
24980 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d  * ^URI hexadecim
24990 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
249a0 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75  ces (%HH) are su
249b0 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74  pported within t
249c0 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71  he path and.** q
249d0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
249e0 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61  of a URI. A hexa
249f0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24a00 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73  equence consists
24a10 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74   of a.** percent
24a20 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f   sign - "%" - fo
24a30 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c  llowed by exactl
24a40 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61  y two hexadecima
24a50 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65  l digits .** spe
24a60 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74  cifying an octet
24a70 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20   value. ^Before 
24a80 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72  the path or quer
24a90 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
24aa0 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  a.** URI filenam
24ab0 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  e are interprete
24ac0 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f  d, they are enco
24ad0 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20  ded using UTF-8 
24ae0 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61  and all .** hexa
24af0 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73  decimal escape s
24b00 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65  equences replace
24b10 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79  d by a single by
24b20 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  te containing th
24b30 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69  e.** correspondi
24b40 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69  ng octet. If thi
24b50 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61  s process genera
24b60 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55  tes an invalid U
24b70 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a  TF-8 encoding,.*
24b80 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  * the results ar
24b90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
24ba0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
24bb0 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e  ndows users:</b>
24bc0 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75    The encoding u
24bd0 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65  sed for the file
24be0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  name argument.**
24bf0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   of sqlite3_open
24c00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
24c10 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65  pen_v2() must be
24c20 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74   UTF-8, not what
24c30 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65  ever.** codepage
24c40 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65   is currently de
24c50 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65  fined.  Filename
24c60 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74  s containing int
24c70 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68  ernational.** ch
24c80 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65  aracters must be
24c90 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54   converted to UT
24ca0 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73  F-8 prior to pas
24cb0 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a  sing them into.*
24cc0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24cd0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
24ce0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  _v2()..**.** <b>
24cf0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
24d00 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f  Runtime users:</
24d10 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72  b>  The temporar
24d20 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74  y directory must
24d30 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72   be set.** prior
24d40 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69   to calling sqli
24d50 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
24d60 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24d70 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72    Otherwise, var
24d80 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73  ious.** features
24d90 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68   that require th
24da0 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61  e use of tempora
24db0 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69  ry files may fai
24dc0 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  l..**.** See als
24dd0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70  o: [sqlite3_temp
24de0 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53  _directory].*/.S
24df0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
24e00 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
24e10 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
24e20 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
24e30 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
24e40 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
24e50 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
24e60 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
24e70 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
24e80 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
24e90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
24ea0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
24eb0 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
24ec0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24ed0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24ee0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24ef0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
24f00 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
24f10 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
24f20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
24f30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
24f40 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
24f50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20  lite3_open_v2(. 
24f60 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
24f70 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
24f80 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
24f90 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
24fa0 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20  e3 **ppDb,      
24fb0 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
24fc0 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  e db handle */. 
24fd0 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20   int flags,     
24fe0 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67           /* Flag
24ff0 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  s */.  const cha
25000 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f  r *zVfs        /
25010 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f  * Name of VFS mo
25020 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29  dule to use */.)
25030 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25040 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73  F: Obtain Values
25050 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74   For URI Paramet
25060 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ers.**.** These 
25070 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74  are utility rout
25080 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20  ines, useful to 
25090 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
250a0 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a  ons, that check.
250b0 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64  ** to see if a d
250c0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73  atabase file was
250d0 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74   a URI that cont
250e0 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63  ained a specific
250f0 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d   query .** param
25100 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20  eter, and if so 
25110 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75  obtains the valu
25120 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20  e of that query 
25130 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
25140 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74   If F is the dat
25150 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70  abase filename p
25160 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e  ointer passed in
25170 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d  to the xOpen() m
25180 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56  ethod of .** a V
25190 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
251a0 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73  n when the flags
251b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
251c0 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72  pen() has one or
251d0 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65   .** more of the
251e0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
251f0 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50  I] or [SQLITE_OP
25200 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73  EN_MAIN_DB] bits
25210 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73   set and.** P is
25220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25230 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25240 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
25250 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
25260 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65  F,P) returns the
25270 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a   value of the P.
25280 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20  ** parameter if 
25290 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e  it exists or a N
252a0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50  ULL pointer if P
252b0 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72   does not appear
252c0 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20   as a .** query 
252d0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20  parameter on F. 
252e0 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79   If P is a query
252f0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a   parameter of F.
25300 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63  ** has no explic
25310 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73  it value, then s
25320 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
25330 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
25340 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
25350 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  o an empty strin
25360 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  g..**.** The sql
25370 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
25380 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20  (F,P,B) routine 
25390 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69  assumes that P i
253a0 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70  s a boolean.** p
253b0 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
253c0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72  urns true (1) or
253d0 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72   false (0) accor
253e0 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75  ding to the valu
253f0 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20  e.** of P.  The 
25400 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25410 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
25420 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ne returns true 
25430 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61  (1) if the.** va
25440 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72  lue of query par
25450 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20  ameter P is one 
25460 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22  of "yes", "true"
25470 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79  , or "on" in any
25480 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74  .** case or if t
25490 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
254a0 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  with a non-zero 
254b0 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a  number.  The .**
254c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
254d0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
254e0 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c  ines returns fal
254f0 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61  se (0) if the va
25500 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20  lue of.** query 
25510 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
25520 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c  ne of "no", "fal
25530 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e  se", or "off" in
25540 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20   any case or.** 
25550 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
25560 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72  ins with a numer
25570 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69  ic zero.  If P i
25580 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a  s not a query.**
25590 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20   parameter on F 
255a0 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
255b0 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74  of P is does not
255c0 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68   match any of th
255d0 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e  e.** above, then
255e0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
255f0 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
25600 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a  rns (B!=0)..**.*
25610 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
25620 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72  i_int64(F,P,D) r
25630 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20  outine converts 
25640 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
25650 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20  nto a.** 64-bit 
25660 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
25670 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20  nd returns that 
25680 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66  integer, or D if
25690 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65   P does not.** e
256a0 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61  xist.  If the va
256b0 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65  lue of P is some
256c0 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
256d0 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
256e0 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74  n.** zero is ret
256f0 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66  urned..** .** If
25700 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69   F is a NULL poi
25710 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  nter, then sqlit
25720 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
25730 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55  (F,P) returns NU
25740 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  LL and.** sqlite
25750 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25760 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20  P,B) returns B. 
25770 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e   If F is not a N
25780 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a  ULL pointer and.
25790 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  ** is not a data
257a0 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61  base file pathna
257b0 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  me pointer that 
257c0 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e  SQLite passed in
257d0 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20  to the xOpen.** 
257e0 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  VFS method, then
257f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
25800 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
25810 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
25820 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73  robably.** undes
25830 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54  irable..*/.SQLIT
25840 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
25850 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
25860 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
25870 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
25880 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
25890 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
258a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
258b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
258c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
258d0 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
258e0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
258f0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
25900 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54  bDefault);.SQLIT
25910 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
25920 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
25930 4c 4c 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69  LL sqlite3_uri_i
25940 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a  nt64(const char*
25950 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73  , const char*, s
25960 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a  qlite3_int64);..
25970 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25980 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64   Error Codes And
25990 20 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54   Messages.** MET
259a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
259b0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
259c0 72 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a  recent sqlite3_*
259d0 20 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69   API call associ
259e0 61 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64  ated with .** [d
259f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25a00 6f 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68  on] D failed, th
25a10 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  en the sqlite3_e
25a20 72 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66  rrcode(D) interf
25a30 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74  ace.** returns t
25a40 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
25a50 6c 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74  lt code] or [ext
25a60 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
25a70 65 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41  e] for that.** A
25a80 50 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74  PI call..** If t
25a90 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
25aa0 50 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63  PI call was succ
25ab0 65 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20  essful,.** then 
25ac0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
25ad0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72   from sqlite3_er
25ae0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
25af0 69 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ined..** ^The sq
25b00 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
25b10 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65  rrcode().** inte
25b20 72 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d  rface is the sam
25b30 65 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  e except that it
25b40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
25b50 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  the .** [extende
25b60 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65  d result code] e
25b70 76 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65  ven when extende
25b80 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
25b90 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a  re.** disabled..
25ba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
25bb0 65 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20  e3_errmsg() and 
25bc0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
25bd0 28 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73  () return Englis
25be0 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65  h-language.** te
25bf0 78 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65  xt that describe
25c00 73 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20  s the error, as 
25c10 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
25c20 55 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76  UTF-16 respectiv
25c30 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79  ely..** ^(Memory
25c40 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72   to hold the err
25c50 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
25c60 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74  g is managed int
25c70 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20  ernally..** The 
25c80 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
25c90 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72   not need to wor
25ca0 72 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67  ry about freeing
25cb0 20 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20   the result..** 
25cc0 48 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72  However, the err
25cd0 6f 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20  or string might 
25ce0 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f  be overwritten o
25cf0 72 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79  r deallocated by
25d00 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63  .** subsequent c
25d10 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51  alls to other SQ
25d20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66  Lite interface f
25d30 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a  unctions.)^.**.*
25d40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
25d50 72 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63  rrstr() interfac
25d60 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e  e returns the En
25d70 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74  glish-language t
25d80 65 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63  ext.** that desc
25d90 72 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c  ribes the [resul
25da0 74 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d  t code], as UTF-
25db0 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  8..** ^(Memory t
25dc0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
25dd0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
25de0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
25df0 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73  nally.** and mus
25e00 74 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62  t not be freed b
25e10 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
25e20 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  n)^..**.** When 
25e30 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
25e40 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
25e50 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69  is in use, it mi
25e60 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61  ght be the.** ca
25e70 73 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64  se that a second
25e80 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e   error occurs on
25e90 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
25ea0 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ad in between.**
25eb0 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65   the time of the
25ec0 20 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64   first error and
25ed0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65   the call to the
25ee0 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  se interfaces..*
25ef0 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70  * When that happ
25f00 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20  ens, the second 
25f10 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65  error will be re
25f20 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65  ported since the
25f30 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
25f40 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74   always report t
25f50 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72  he most recent r
25f60 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64  esult.  To avoid
25f70 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74  .** this, each t
25f80 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e  hread can obtain
25f90 20 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f   exclusive use o
25fa0 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
25fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a  connection] D.**
25fc0 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71   by invoking [sq
25fd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65  lite3_mutex_ente
25fe0 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  r]([sqlite3_db_m
25ff0 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65  utex](D)) before
26000 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f   beginning.** to
26010 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b   use D and invok
26020 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  ing [sqlite3_mut
26030 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74  ex_leave]([sqlit
26040 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29  e3_db_mutex](D))
26050 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61   after.** all ca
26060 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72  lls to the inter
26070 66 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72  faces listed her
26080 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e  e are completed.
26090 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74  .**.** If an int
260a0 65 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74  erface fails wit
260b0 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c  h SQLITE_MISUSE,
260c0 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
260d0 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73  interface.** was
260e0 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65   invoked incorre
260f0 63 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c  ctly by the appl
26100 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61  ication.  In tha
26110 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65  t case, the.** e
26120 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65  rror code and me
26130 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79  ssage may or may
26140 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a   not be set..*/.
26150 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
26160 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
26170 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
26180 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
26190 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
261a0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
261b0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
261c0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
261d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
261e0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
261f0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
26200 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
26210 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
26220 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
26230 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
26240 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
26250 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
26260 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
26270 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
26280 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f  _errstr(int);../
26290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
262a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
262b0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  t Object.** KEYW
262c0 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20  ORDS: {prepared 
262d0 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70  statement} {prep
262e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d  ared statements}
262f0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
26300 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
26310 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73  t represents a s
26320 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
26330 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20  ent that.** has 
26340 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e  been compiled in
26350 74 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61  to binary form a
26360 6e 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62  nd is ready to b
26370 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
26380 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68  ** Think of each
26390 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
263a0 73 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d  s a separate com
263b0 70 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20  puter program.  
263c0 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  The.** original 
263d0 53 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72  SQL text is sour
263e0 63 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70  ce code.  A prep
263f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
26400 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65  bject .** is the
26410 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74   compiled object
26420 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20   code.  All SQL 
26430 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
26440 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70  d into a.** prep
26450 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62  ared statement b
26460 65 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20  efore it can be 
26470 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  run..**.** The l
26480 69 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70  ife-cycle of a p
26490 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264a0 74 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79  t object usually
264b0 20 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a   goes like this:
264c0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
264d0 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70  li> Create the p
264e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
264f0 74 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  t object using [
26500 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
26510 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  v2()]..** <li> B
26520 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70  ind values to [p
26530 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67  arameters] using
26540 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26550 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e  d_*().**      in
26560 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69  terfaces..** <li
26570 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79  > Run the SQL by
26580 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
26590 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72  3_step()] one or
265a0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
265b0 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70  <li> Reset the p
265c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
265d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
265e0 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
265f0 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
26600 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
26610 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
26620 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
26630 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
26640 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
26650 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
26660 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65   </ol>.*/.typede
26670 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
26680 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74  _stmt sqlite3_st
26690 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  mt;../*.** CAPI3
266a0 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69  REF: Run-time Li
266b0 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  mits.** METHOD: 
266c0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28  sqlite3.**.** ^(
266d0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
266e0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
266f0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
26700 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
26710 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
26720 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
26730 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
26740 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26750 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
26760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26770 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
26780 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
26790 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
267a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
267b0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
267c0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
267d0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
267e0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
267f0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
26800 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
26810 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
26820 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
26830 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
26840 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
26850 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
26860 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
26870 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
26880 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
26890 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
268a0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
268b0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
268c0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
268d0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
268e0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
268f0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
26900 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
26910 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
26920 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
26930 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
26940 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
26950 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
26960 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
26970 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
26980 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
26990 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
269a0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
269b0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
269c0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
269d0 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
269e0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
269f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
26a00 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26a10 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
26a20 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
26a30 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
26a40 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
26a50 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
26a60 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
26a70 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
26a80 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
26a90 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
26aa0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
26ab0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
26ac0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
26ad0 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
26ae0 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
26af0 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
26b00 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
26b10 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
26b20 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
26b30 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
26b40 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
26b50 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
26b60 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
26b70 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
26b80 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
26b90 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
26ba0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
26bb0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
26bc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
26bd0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
26be0 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
26bf0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
26c00 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
26c10 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
26c20 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
26c30 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
26c40 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
26c50 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
26c60 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
26c70 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
26c80 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
26c90 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
26ca0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
26cb0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
26cc0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
26cd0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
26ce0 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
26cf0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
26d00 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
26d10 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
26d20 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
26d30 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
26d40 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
26d50 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
26d60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
26d70 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
26d80 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
26d90 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
26da0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
26db0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
26dc0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
26dd0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
26de0 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
26df0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
26e00 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
26e10 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
26e20 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
26e30 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
26e40 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
26e50 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
26e60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
26e70 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
26e80 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  LL sqlite3_limit
26e90 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
26ea0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
26eb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26ec0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
26ed0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
26ee0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
26ef0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
26f00 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
26f10 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26f20 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
26f30 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
26f40 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
26f50 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
26f60 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
26f70 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
26f80 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
26f90 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
26fa0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
26fb0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
26fc0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
26fd0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
26fe0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
26ff0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
27000 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
27010 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
27020 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
27030 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
27040 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
27050 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27060 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
27070 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
27080 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
27090 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
270a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
270b0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
270c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
270d0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
270e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
270f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
27100 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
27110 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
27120 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27130 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
27140 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27150 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
27160 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27170 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
27180 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
27190 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
271a0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
271b0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
271c0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
271d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
271e0 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
271f0 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
27200 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
27210 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
27220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27230 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
27240 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27250 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
27260 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27270 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
27280 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
27290 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
272a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
272b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
272c0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
272d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
272e0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
272f0 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
27300 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27310 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
27320 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
27330 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
27340 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27350 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
27360 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27370 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
27380 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27390 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
273a0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
273b0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
273c0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
273d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
273e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
273f0 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
27400 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
27410 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
27420 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
27430 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
27440 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
27450 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
27460 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27470 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
27480 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
27490 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
274a0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
274b0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
274c0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
274d0 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
274e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
274f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
27500 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
27510 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
27520 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
27530 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
27540 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
27550 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
27560 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
27570 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
27580 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
27590 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
275a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
275b0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
275c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
275d0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
275e0 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
275f0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
27600 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
27610 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
27620 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27630 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27640 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
27650 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27660 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
27670 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27680 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
27690 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
276a0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
276b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
276c0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
276d0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
276e0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
276f0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27700 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
27710 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
27720 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
27730 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
27740 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27750 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
27760 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
27770 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
27780 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
27790 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
277a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
277b0 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
277c0 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
277d0 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
277e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
277f0 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
27800 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
27810 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27820 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
27830 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
27840 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27850 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
27860 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
27870 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27880 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
27890 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
278a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
278b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
278c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
278d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
278e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
278f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
27900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27910 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
27920 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27930 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
27940 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27950 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
27960 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
27970 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
27980 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27990 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
279a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
279b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
279c0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
279d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
279e0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
279f0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
27a00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
27a10 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
27a20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
27a30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
27a40 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
27a50 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
27a60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
27a70 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
27a80 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
27a90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
27aa0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54  compiler}.** MET
27ab0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
27ac0 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
27ad0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
27ae0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
27af0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
27b00 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
27b10 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
27b20 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
27b30 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
27b40 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
27b50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
27b60 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
27b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27b80 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
27b90 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
27ba0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
27bb0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
27bc0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
27bd0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
27be0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
27bf0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
27c00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
27c10 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
27c20 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
27c30 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
27c40 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
27c50 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
27c60 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
27c70 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
27c80 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
27c90 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
27ca0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
27cb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27cc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
27cd0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
27ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27cf0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
27d00 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
27d10 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
27d20 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
27d30 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
27d40 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
27d50 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
27d60 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
27d70 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
27d80 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
27d90 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
27da0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
27db0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
27dc0 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
27dd0 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
27de0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
27df0 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
27e00 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
27e10 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
27e20 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
27e30 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
27e40 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
27e50 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
27e60 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
27e70 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
27e80 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
27e90 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
27ea0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27eb0 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
27ec0 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
27ed0 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
27ee0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
27ef0 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
27f00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
27f10 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
27f20 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
27f30 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
27f40 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
27f50 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
27f60 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
27f70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
27f80 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
27f90 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
27fa0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
27fb0 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
27fc0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
27fd0 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
27fe0 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
27ff0 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
28000 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
28010 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
28020 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
28030 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
28040 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
28050 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
28060 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
28070 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
28080 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
28090 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
280a0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
280b0 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
280c0 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
280d0 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
280e0 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
280f0 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
28100 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
28110 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
28120 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
28130 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
28140 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
28150 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
28160 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
28170 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
28180 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
28190 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
281a0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
281b0 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
281c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
281d0 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
281e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
281f0 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
28200 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
28210 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
28220 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
28230 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28240 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
28250 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
28260 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
28270 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
28280 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
28290 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
282a0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
282b0 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
282c0 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
282d0 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
282e0 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
282f0 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
28300 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
28310 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
28320 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
28330 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
28340 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
28350 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
28360 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
28370 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
28380 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
28390 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
283a0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
283b0 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
283c0 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
283d0 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
283e0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
283f0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
28400 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
28410 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
28420 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
28430 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
28440 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
28450 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
28460 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
28470 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
28480 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
28490 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
284a0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
284b0 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
284c0 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
284d0 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
284e0 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
284f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
28500 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
28510 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
28520 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
28530 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
28540 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
28550 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
28560 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
28570 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
28580 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
28590 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
285a0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
285b0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
285c0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
285d0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
285e0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
285f0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
28600 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
28610 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
28620 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
28630 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
28640 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
28650 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
28660 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
28670 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
28680 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
28690 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
286a0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
286b0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
286c0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
286d0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
286e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
286f0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
28700 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
28710 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
28720 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
28730 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
28740 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
28750 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
28760 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
28770 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
28780 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
28790 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
287a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
287b0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
287c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
287d0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
287e0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
287f0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
28800 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
28810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28820 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
28830 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
28840 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
28850 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
28860 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
28870 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
28880 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
28890 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
288a0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
288b0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
288c0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
288d0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
288e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
288f0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
28900 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
28910 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
28920 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
28930 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
28940 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
28950 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
28960 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
28970 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
28980 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
28990 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
289a0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
289b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
289c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
289d0 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73  te3_prepare(.  s
289e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
289f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28a00 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
28a10 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
28a20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
28a30 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
28a40 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28a50 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28a60 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28a70 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28a80 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28a90 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28aa0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28ab0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28ac0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
28ad0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28ae0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28af0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28b00 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
28b10 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28b20 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28b30 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
28b40 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
28b50 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
28b60 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
28b70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
28b80 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
28b90 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
28ba0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28bb0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28bc0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28bd0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28be0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28bf0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28c00 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28c10 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28c20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
28c30 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28c40 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28c50 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28c60 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
28c70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28c80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28c90 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
28ca0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
28cb0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
28cc0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
28cd0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
28ce0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
28cf0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
28d00 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
28d10 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
28d20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
28d30 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
28d40 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
28d50 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
28d60 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
28d70 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
28d80 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
28d90 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
28da0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
28db0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
28dc0 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
28dd0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
28de0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
28df0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28e00 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28e10 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28e20 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28e30 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28e40 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28e50 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28e60 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28e70 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28e80 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28e90 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28ea0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28ec0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28ed0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28ee0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28ef0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28f00 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28f10 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28f20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
28f30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28f40 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
28f50 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f  ent SQL.** METHO
28f60 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
28f70 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
28f80 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
28f90 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
28fa0 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
28fb0 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
28fc0 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
28fd0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
28fe0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
28ff0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
29000 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
29010 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
29020 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
29030 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
29040 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
29050 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
29060 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
29070 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
29080 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  _sql(sqlite3_stm
29090 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
290a0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65  * CAPI3REF: Dete
290b0 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20  rmine If An SQL 
290c0 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73  Statement Writes
290d0 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a   The Database.**
290e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
290f0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
29100 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29110 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
29120 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
29130 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
29140 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
29150 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29160 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
29170 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
29180 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
29190 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
291a0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
291b0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
291c0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
291d0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
291e0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
291f0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
29200 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
29210 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
29220 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
29230 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
29240 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
29250 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
29260 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
29270 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
29280 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
29290 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
292a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
292b0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
292c0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
292d0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
292e0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
292f0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
29300 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
29310 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
29320 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
29330 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
29340 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
29350 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
29360 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
29370 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
29380 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
29390 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
293a0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
293b0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
293c0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
293d0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
293e0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
293f0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
29400 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
29410 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
29420 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
29430 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
29440 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
29450 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
29460 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
29470 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
29480 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
29490 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
294a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
294b0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
294c0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
294d0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
294e0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
294f0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
29500 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
29510 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
29520 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
29530 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
29540 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29550 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
29560 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
29570 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
29580 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
29590 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
295a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
295b0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
295c0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
295d0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
295e0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
295f0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
29600 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29610 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
29620 4c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  L sqlite3_stmt_r
29630 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
29640 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29660 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
29670 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29680 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
29690 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
296a0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
296b0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
296c0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
296d0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
296e0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
296f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
29700 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
29710 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
29720 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
29730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
29740 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
29750 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
29760 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
29770 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
29780 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
29790 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
297a0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
297b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
297c0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
297d0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
297e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
297f0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
29800 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
29810 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
29820 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
29830 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
29840 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
29850 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
29860 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
29870 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
29880 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
29890 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
298a0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
298b0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
298c0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
298d0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
298e0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
298f0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
29900 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
29910 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
29920 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
29930 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
29940 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
29950 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
29960 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
29970 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
29980 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
29990 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
299a0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
299b0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
299c0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
299d0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
299e0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49  on open..*/.SQLI
299f0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
29a00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
29a10 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
29a20 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
29a30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
29a40 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
29a50 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
29a60 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
29a70 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29a80 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
29a90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
29aa0 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
29ab0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
29ac0 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
29ad0 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
29ae0 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
29af0 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
29b00 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
29b10 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
29b20 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
29b30 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
29b40 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
29b50 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
29b60 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
29b70 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
29b80 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
29b90 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
29ba0 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
29bb0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
29bc0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29bd0 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
29be0 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
29bf0 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
29c00 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
29c10 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
29c20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29c30 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
29c40 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
29c50 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
29c60 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
29c70 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29c80 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
29c90 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
29ca0 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
29cb0 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
29cc0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
29cd0 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
29ce0 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
29cf0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29d00 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  The.** [sqlit
29d10 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 20  e3_value_dup()] 
29d20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
29d30 20 75 73 65 64 20 74 6f 20 63 6f 6e 73 74 72 75   used to constru
29d40 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f  ct a new .** pro
29d50 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29d60 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70  alue from an unp
29d70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29d80 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  _value..**.** Th
29d90 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74  e terms "protect
29da0 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65  ed" and "unprote
29db0 63 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77  cted" refer to w
29dc0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a  hether or not.**
29dd0 20 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64   a mutex is held
29de0 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d  .  An internal m
29df0 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
29e00 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   a protected.** 
29e10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29e20 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65  ject but no mute
29e30 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e  x is held for an
29e40 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29e50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29e60 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65  ject.  If SQLite
29e70 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20   is compiled to 
29e80 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  be single-thread
29e90 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c  ed.** (with [SQL
29ea0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
29eb0 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69  ] and with [sqli
29ec0 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
29ed0 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a  ] returning 0).*
29ee0 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69  * or if SQLite i
29ef0 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20  s run in one of 
29f00 72 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f  reduced mutex mo
29f10 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  des .** [SQLITE_
29f20 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
29f30 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  EAD] or [SQLITE_
29f40 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
29f50 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72  AD].** then ther
29f60 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74  e is no distinct
29f70 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
29f80 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
29f90 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
29fa0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61  _value objects a
29fb0 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75  nd they can be u
29fc0 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61  sed interchangea
29fd0 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  bly.  However,.*
29fe0 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f  * for maximum co
29ff0 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69  de portability i
2a000 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
2a010 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
2a020 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65  ns.** still make
2a030 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
2a040 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2a050 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2a060 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2a070 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e  lue objects even
2a080 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74   when not strict
2a090 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  ly required..**.
2a0a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2a0b0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68  value objects th
2a0c0 61 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73  at are passed as
2a0d0 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f   parameters into
2a0e0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
2a0f0 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69  tation of [appli
2a100 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2a110 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72  QL functions] ar
2a120 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  e protected..** 
2a130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2a140 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ue object return
2a150 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
2a160 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2a170 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64  ] is unprotected
2a180 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64  ..** Unprotected
2a190 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a1a0 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20  bjects may only 
2a1b0 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20  be used with.** 
2a1c0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
2a1d0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2a1e0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2a1f0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ()]..** The [sql
2a200 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20  ite3_value_blob 
2a210 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  | sqlite3_value_
2a220 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f  type()] family o
2a230 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  f.** interfaces 
2a240 72 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65  require protecte
2a250 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2a260 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65  objects..*/.type
2a270 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73  def struct Mem s
2a280 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f  qlite3_value;../
2a290 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2a2a0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  QL Function Cont
2a2b0 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ext Object.**.**
2a2c0 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20   The context in 
2a2d0 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e  which an SQL fun
2a2e0 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69  ction executes i
2a2f0 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a  s stored in an.*
2a300 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  * sqlite3_contex
2a310 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f  t object.  ^A po
2a320 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69  inter to an sqli
2a330 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2a340 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ct.** is always 
2a350 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2a360 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  to [application-
2a370 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a380 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61  tions]..** The a
2a390 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a3a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2a3b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2a3c0 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a  ill pass this.**
2a3d0 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68   pointer through
2a3e0 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b   into calls to [
2a3f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
2a400 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73  nt | sqlite3_res
2a410 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ult()],.** [sqli
2a420 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2a430 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74  ntext()], [sqlit
2a440 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c  e3_user_data()],
2a450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
2a460 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
2a470 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ], [sqlite3_get_
2a480 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61  auxdata()],.** a
2a490 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  nd/or [sqlite3_s
2a4a0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a  et_auxdata()]..*
2a4b0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2a4c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2a4d0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2a4e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a4f0 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65  F: Binding Value
2a500 73 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74  s To Prepared St
2a510 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57  atements.** KEYW
2a520 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61  ORDS: {host para
2a530 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72  meter} {host par
2a540 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70  ameters} {host p
2a550 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a  arameter name}.*
2a560 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
2a570 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c   parameter} {SQL
2a580 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61   parameters} {pa
2a590 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d  rameter binding}
2a5a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2a5b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2a5c0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2a5d0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2a5e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2a5f0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2a600 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2a610 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2a620 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2a630 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2a640 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2a650 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2a660 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2a670 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2a680 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2a690 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2a6a0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2a6b0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2a6c0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2a6d0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2a6e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2a6f0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2a700 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2a710 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2a720 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2a730 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2a740 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2a750 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2a760 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2a770 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2a780 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2a790 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2a7a0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2a7b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2a7c0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2a7d0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2a7e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2a7f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2a800 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2a810 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2a820 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2a830 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2a840 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2a850 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a860 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2a870 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2a880 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2a890 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2a8a0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2a8b0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2a8c0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2a8d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2a8e0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2a8f0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2a900 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2a910 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2a920 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2a930 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2a940 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2a950 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2a960 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2a970 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2a980 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2a990 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2a9a0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2a9b0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2a9c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2a9d0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a9e0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2a9f0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2aa00 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2aa10 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2aa20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2aa30 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2aa40 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2aa50 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2aa60 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2aa70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2aa80 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2aa90 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2aaa0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2aab0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2aac0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2aad0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2aae0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2aaf0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2ab00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2ab10 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2ab20 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2ab30 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20  _text16().** or 
2ab40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ab50 62 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  b() is a NULL po
2ab60 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 66  inter then the f
2ab70 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 0a  ourth parameter.
2ab80 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64 20 61 6e  ** is ignored an
2ab90 64 20 74 68 65 20 65 6e 64 20 72 65 73 75 6c 74  d the end result
2aba0 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
2abb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2abc0 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  l()..**.** ^(In 
2abd0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2abe0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2abf0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2ac00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2ac10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2ac20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2ac30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2ac40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2ac50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2ac60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2ac70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2ac80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2ac90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2aca0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2acb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2acc0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2acd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ace0 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2acf0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2ad00 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2ad10 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2ad20 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2ad30 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2ad40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2ad50 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2ad60 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2ad70 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2ad80 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2ad90 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2ada0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2adb0 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2adc0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2add0 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2ade0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2adf0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2ae00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ae10 31 36 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  16() or sqlite3_
2ae20 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 74 68  bind_text64() th
2ae30 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61 72 61 6d  en.** that param
2ae40 65 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65  eter must be the
2ae50 20 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20   byte offset.** 
2ae60 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
2ae70 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f  rminator would o
2ae80 63 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68  ccur assuming th
2ae90 65 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55  e string were NU
2aea0 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e  L.** terminated.
2aeb0 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61    If any NUL cha
2aec0 72 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74  racters occur at
2aed0 20 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65   byte offsets le
2aee0 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20  ss than .** the 
2aef0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75  value of the fou
2af00 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68  rth parameter th
2af10 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  en the resulting
2af20 20 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69   string value wi
2af30 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d  ll.** contain em
2af40 62 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68  bedded NULs.  Th
2af50 65 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  e result of expr
2af60 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e  essions involvin
2af70 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74  g strings.** wit
2af80 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
2af90 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2afa0 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
2afb0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 42  rgument to the B
2afc0 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e 67 20 62  LOB and string b
2afd0 69 6e 64 69 6e 67 20 69 6e 74 65 72 66 61 63 65  inding interface
2afe0 73 0a 2a 2a 20 69 73 20 61 20 64 65 73 74 72 75  s.** is a destru
2aff0 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69 73  ctor used to dis
2b000 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2b010 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66   or.** string af
2b020 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20 66  ter SQLite has f
2b030 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
2b040 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f    ^The destructo
2b050 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  r is called.** t
2b060 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2b070 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 20   BLOB or string 
2b080 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c 6c  even if the call
2b090 20 74 6f 20 62 69 6e 64 20 41 50 49 20 66 61 69   to bind API fai
2b0a0 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ls..** ^If the f
2b0b0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2b0c0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2b0d0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2b0e0 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2b0f0 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2b100 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2b110 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2b120 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2b130 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2b140 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2b150 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2b160 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2b170 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2b180 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2b190 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2b1a0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2b1b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2b1c0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2b1d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2b1e0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2b1f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2b200 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 20  *.** ^The sixth 
2b210 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2b220 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2b230 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66  ) must be one of
2b240 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
2b250 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2b260 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  ], [SQLITE_UTF16
2b270 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  BE], or [SQLITE_
2b280 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73  UTF16LE].** to s
2b290 70 65 63 69 66 79 20 74 68 65 20 65 6e 63 6f 64  pecify the encod
2b2a0 69 6e 67 20 6f 66 20 74 68 65 20 74 65 78 74 20  ing of the text 
2b2b0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
2b2c0 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74  ameter.  If.** t
2b2d0 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2b2e0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2b2f0 64 5f 74 65 78 74 36 34 28 29 20 69 73 20 6e 6f  d_text64() is no
2b300 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
2b310 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65 73 20 73  allowed values s
2b320 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69  hown above, or i
2b330 66 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  f the text encod
2b340 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74  ing is different
2b350 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 65 6e 63  .** from the enc
2b360 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64 20  oding specified 
2b370 62 79 20 74 68 65 20 73 69 78 74 68 20 70 61 72  by the sixth par
2b380 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
2b390 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20   behavior.** is 
2b3a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2b3b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2b3c0 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f  nd_zeroblob() ro
2b3d0 75 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c  utine binds a BL
2b3e0 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74  OB of length N t
2b3f0 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64  hat.** is filled
2b400 20 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e   with zeroes.  ^
2b410 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20  A zeroblob uses 
2b420 61 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f  a fixed amount o
2b430 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73  f memory.** (jus
2b440 74 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20  t an integer to 
2b450 68 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77  hold its size) w
2b460 68 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67  hile it is being
2b470 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a   processed..** Z
2b480 65 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74  eroblobs are int
2b490 65 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61  ended to serve a
2b4a0 73 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  s placeholders f
2b4b0 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a  or BLOBs whose.*
2b4c0 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74  * content is lat
2b4d0 65 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67  er written using
2b4e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2b4f0 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
2b500 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72  ntal BLOB I/O] r
2b510 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e  outines..** ^A n
2b520 65 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f  egative value fo
2b530 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72  r the zeroblob r
2b540 65 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f  esults in a zero
2b550 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a  -length BLOB..**
2b560 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74  .** ^If any of t
2b570 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2b580 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  *() routines are
2b590 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
2b5a0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66  ULL pointer.** f
2b5b0 6f 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  or the [prepared
2b5c0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77   statement] or w
2b5d0 69 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73  ith a prepared s
2b5e0 74 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69  tatement for whi
2b5f0 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  ch.** [sqlite3_s
2b600 74 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20  tep()] has been 
2b610 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65  called more rece
2b620 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74  ntly than [sqlit
2b630 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20  e3_reset()],.** 
2b640 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69  then the call wi
2b650 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
2b660 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61  E_MISUSE].  If a
2b670 6e 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ny sqlite3_bind_
2b680 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73  ().** routine is
2b690 20 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61   passed a [prepa
2b6a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2b6b0 68 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e  hat has been fin
2b6c0 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72  alized, the.** r
2b6d0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2b6e0 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
2b6f0 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  harmful..**.** ^
2b700 42 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74  Bindings are not
2b710 20 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20   cleared by the 
2b720 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b730 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55  ] routine..** ^U
2b740 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  nbound parameter
2b750 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
2b760 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  d as NULL..**.**
2b770 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2b780 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65  nd_* routines re
2b790 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
2b7a0 20 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61   on success or a
2b7b0 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65  n.** [error code
2b7c0 5d 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f  ] if anything go
2b7d0 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53  es wrong..** ^[S
2b7e0 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69  QLITE_TOOBIG] mi
2b7f0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2b800 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  if the size of a
2b810 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a   string or BLOB.
2b820 2a 2a 20 65 78 63 65 65 64 73 20 6c 69 6d 69 74  ** exceeds limit
2b830 73 20 69 6d 70 6f 73 65 64 20 62 79 20 5b 73 71  s imposed by [sq
2b840 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
2b850 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b860 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  H]) or.** [SQLIT
2b870 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a  E_MAX_LENGTH]..*
2b880 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
2b890 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
2b8a0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
2b8b0 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
2b8c0 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
2b8d0 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
2b8e0 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
2b8f0 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
2b900 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2b910 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2b920 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
2b930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b940 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
2b950 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
2b960 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b970 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2b980 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2b990 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2b9a0 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2b9b0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b9c0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2b9d0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b9e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b9f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2ba00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2ba10 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2ba20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2ba30 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
2ba40 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  64,.            
2ba50 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
2ba60 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2ba70 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2ba80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2ba90 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2baa0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bab0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
2bac0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2bad0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bae0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2baf0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2bb00 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2bb10 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2bb20 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2bb30 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
2bb40 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
2bb50 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45  3_int64);.SQLITE
2bb60 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
2bb70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2bb80 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
2bb90 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
2bba0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2bbb0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2bbc0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2bbd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2bbe0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2bbf0 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2bc00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2bc10 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2bc20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2bc30 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2bc40 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2bc50 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2bc60 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2bc70 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2bc80 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2bc90 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
2bca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2bcb0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2bcc0 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2bcd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bce0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2bcf0 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
2bd00 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
2bd10 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2bd20 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2bd30 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2bd40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bd50 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
2bd60 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
2bd70 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2bd80 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bd90 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2bda0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bdb0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49  nt, int n);.SQLI
2bdc0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2bdd0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2bde0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36  3_bind_zeroblob6
2bdf0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2be00 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69   int, sqlite3_ui
2be10 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt64);../*.** CA
2be20 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2be30 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
2be40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2be50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2be60 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2be70 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2be80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2be90 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2bea0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2beb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2bec0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2bed0 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2bee0 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2bef0 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2bf00 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2bf10 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2bf20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2bf30 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2bf40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bf50 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2bf60 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2bf70 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2bf80 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2bf90 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2bfa0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2bfb0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2bfc0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2bfd0 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2bfe0 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2bff0 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2c000 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2c010 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2c020 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2c030 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2c040 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2c050 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2c060 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2c070 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2c080 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c090 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c0a0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2c0b0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c0c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c0d0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2c0e0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c0f0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2c100 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c110 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2c120 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2c130 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2c140 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c150 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c160 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2c170 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d 45 54  Parameter.** MET
2c180 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c190 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2c1a0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c1b0 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e  ter_name(P,N) in
2c1c0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a  terface returns.
2c1d0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ** the name of t
2c1e0 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72  he N-th [SQL par
2c1f0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b  ameter] in the [
2c200 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c210 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20  nt] P..** ^(SQL 
2c220 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  parameters of th
2c230 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72  e form "?NNN" or
2c240 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2c250 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68  " or "$AAA".** h
2c260 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68  ave a name which
2c270 20 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22   is the string "
2c280 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2c290 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2c2a0 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  AA".** respectiv
2c2b0 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  ely..** In other
2c2c0 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74   words, the init
2c2d0 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f  ial ":" or "$" o
2c2e0 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20  r "@" or "?".** 
2c2f0 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70  is included as p
2c300 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e  art of the name.
2c310 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72  )^.** ^Parameter
2c320 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
2c330 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c  " without a foll
2c340 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61  owing integer ha
2c350 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e  ve no name.** an
2c360 64 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74  d are referred t
2c370 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20  o as "nameless" 
2c380 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61  or "anonymous pa
2c390 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a  rameters"..**.**
2c3a0 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74   ^The first host
2c3b0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2c3c0 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f  n index of 1, no
2c3d0 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t 0..**.** ^If t
2c3e0 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75  he value N is ou
2c3f0 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66  t of range or if
2c400 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65   the N-th parame
2c410 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65  ter is.** namele
2c420 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73  ss, then NULL is
2c430 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65   returned.  ^The
2c440 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2c450 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e   is.** always in
2c460 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
2c470 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65  even if the name
2c480 64 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a  d parameter was.
2c490 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70  ** originally sp
2c4a0 65 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31  ecified as UTF-1
2c4b0 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  6 in [sqlite3_pr
2c4c0 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a  epare16()] or.**
2c4d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c4e0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2c4f0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2c500 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2c510 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2c520 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2c530 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2c540 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2c550 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c560 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2c570 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2c580 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54   char *SQLITE_ST
2c590 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2c5a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2c5b0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2c5c0 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2c5d0 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2c5e0 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2c5f0 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2c600 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c610 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
2c620 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
2c630 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
2c640 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
2c650 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
2c660 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
2c670 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
2c680 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
2c690 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
2c6a0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
2c6b0 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c6c0 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
2c6d0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
2c6e0 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
2c6f0 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
2c700 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
2c710 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
2c720 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
2c730 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
2c740 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
2c750 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
2c760 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
2c770 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2c780 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2c790 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2c7a0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c7b0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2c7c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c7d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c7e0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
2c7f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2c800 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2c810 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c820 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2c830 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2c840 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2c850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2c860 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2c870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c880 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2c890 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2c8a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2c8b0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c8c0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  3_stmt.**.** ^Co
2c8d0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2c8e0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2c8f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c900 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2c910 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2c920 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2c930 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2c940 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c950 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2c960 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2c970 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2c980 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2c990 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c9a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2c9b0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
2c9c0 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2c9d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2c9e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
2c9f0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
2ca00 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
2ca10 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ca20 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2ca30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ca40 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2ca50 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20  lt set returned 
2ca60 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  by the.** [prepa
2ca70 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2ca80 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
2ca90 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74  turns 0 if pStmt
2caa0 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74   is an SQL.** st
2cab0 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65  atement that doe
2cac0 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74  s not return dat
2cad0 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61  a (for example a
2cae0 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a  n [UPDATE])..**.
2caf0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2cb00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2cb10 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()].*/.SQLITE_AP
2cb20 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2cb30 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2cb40 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2cb50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2cb60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cb70 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2cb80 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2cb90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2cba0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2cbb0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2cbc0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2cbd0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2cbe0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2cbf0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2cc00 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2cc10 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2cc20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2cc30 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2cc40 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2cc50 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2cc60 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2cc70 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2cc80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2cc90 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2cca0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2ccb0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2ccc0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2ccd0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2cce0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2ccf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cd00 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2cd10 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2cd20 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2cd30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2cd40 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2cd50 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2cd60 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2cd70 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2cd80 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2cd90 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2cda0 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2cdb0 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2cdc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2cdd0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2cde0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2cdf0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2ce00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2ce10 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2ce20 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2ce30 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2ce40 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2ce50 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2ce60 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2ce70 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2ce80 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2ce90 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2cea0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2ceb0 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2cec0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2ced0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2cee0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2cef0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2cf00 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2cf10 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2cf20 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2cf30 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2cf40 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2cf50 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2cf60 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2cf70 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2cf80 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2cf90 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2cfa0 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2cfb0 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2cfc0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2cfd0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2cfe0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2cff0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2d000 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2d010 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2d020 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2d030 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2d040 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2d050 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2d060 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
2d070 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d080 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2d090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2d0a0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2d0b0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49  t*, int N);.SQLI
2d0c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2d0d0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2d0e0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2d0f0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2d100 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2d110 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d120 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2d130 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2d140 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d150 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d160 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70  These routines p
2d170 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74  rovide a means t
2d180 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  o determine the 
2d190 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2d1a0 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f   and.** table co
2d1b0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65  lumn that is the
2d1c0 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72   origin of a par
2d1d0 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63  ticular result c
2d1e0 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c  olumn in.** [SEL
2d1f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a  ECT] statement..
2d200 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2d210 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20  the database or 
2d220 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20  table or column 
2d230 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20  can be returned 
2d240 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55  as.** either a U
2d250 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73  TF-8 or UTF-16 s
2d260 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61  tring.  ^The _da
2d270 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73  tabase_ routines
2d280 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64   return.** the d
2d290 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68  atabase name, th
2d2a0 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e  e _table_ routin
2d2b0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61  es return the ta
2d2c0 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a  ble name, and.**
2d2d0 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75   the origin_ rou
2d2e0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2d2f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a   column name..**
2d300 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2d310 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75  tring is valid u
2d320 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72  ntil the [prepar
2d330 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73  ed statement] is
2d340 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73   destroyed.** us
2d350 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
2d360 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69  alize()] or unti
2d370 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  l the statement 
2d380 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  is automatically
2d390 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62  .** reprepared b
2d3a0 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c  y the first call
2d3b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2d3c0 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69  p()] for a parti
2d3d0 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20  cular run.** or 
2d3e0 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69  until the same i
2d3f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65  nformation is re
2d400 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e  quested.** again
2d410 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20   in a different 
2d420 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  encoding..**.** 
2d430 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72  ^The names retur
2d440 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67  ned are the orig
2d450 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20  inal un-aliased 
2d460 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20  names of the.** 
2d470 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2d480 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a   and column..**.
2d490 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
2d4a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20  gument to these 
2d4b0 69 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20  interfaces is a 
2d4c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d4d0 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20  ent]..** ^These 
2d4e0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2d4f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
2d500 75 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c  ut the Nth resul
2d510 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  t column returne
2d520 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74  d by.** the stat
2d530 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69  ement, where N i
2d540 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e  s the second fun
2d550 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a  ction argument..
2d560 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73  ** ^The left-mos
2d570 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75  t column is colu
2d580 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72  mn 0 for these r
2d590 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
2d5a0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2d5b0 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  n returned by th
2d5c0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d5d0 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a  n expression or.
2d5e0 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20  ** subquery and 
2d5f0 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20  is not a column 
2d600 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20  value, then all 
2d610 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
2d620 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c  ns return.** NUL
2d630 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  L.  ^These routi
2d640 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65  ne might also re
2d650 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d  turn NULL if a m
2d660 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2d670 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73   error.** occurs
2d680 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74  .  ^Otherwise, t
2d690 68 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e  hey return the n
2d6a0 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63  ame of the attac
2d6b0 68 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61  hed database, ta
2d6c0 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d  ble,.** or colum
2d6d0 6e 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73  n that query res
2d6e0 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65  ult column was e
2d6f0 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a  xtracted from..*
2d700 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c  *.** ^As with al
2d710 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41  l other SQLite A
2d720 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65  PIs, those whose
2d730 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20   names end with 
2d740 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55  "16" return.** U
2d750 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74  TF-16 encoded st
2d760 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74  rings and the ot
2d770 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  her functions re
2d780 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a  turn UTF-8..**.*
2d790 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72  * ^These APIs ar
2d7a0 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  e only available
2d7b0 20 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20   if the library 
2d7c0 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
2d7d0 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
2d7e0 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d  _ENABLE_COLUMN_M
2d7f0 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72  ETADATA] C-prepr
2d800 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a  ocessor symbol..
2d810 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
2d820 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
2d830 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  l one or more of
2d840 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d850 61 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65  against the same
2d860 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
2d870 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d  tement and colum
2d880 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  n at the same ti
2d890 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  me then the resu
2d8a0 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66  lts are.** undef
2d8b0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ined..**.** If t
2d8c0 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61  wo or more threa
2d8d0 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d  ds call one or m
2d8e0 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
2d8f0 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2d900 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65  name | column me
2d910 74 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65  tadata interface
2d920 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  s].** for the sa
2d930 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
2d940 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75  tement] and resu
2d950 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20  lt column.** at 
2d960 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68  the same time th
2d970 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
2d980 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
2d990 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d9a0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2d9b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2d9c0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2d9d0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2d9e0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d9f0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
2da00 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2da10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
2da20 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
2da30 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2da40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2da50 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2da60 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2da70 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2da80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2da90 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2daa0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2dab0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2dac0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2dad0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2dae0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2daf0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2db00 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2db10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2db20 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69  origin_name(sqli
2db30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2db40 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2db50 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2db60 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2db70 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2db80 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2db90 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2dba0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2dbb0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2dbc0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2dbd0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2dbe0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
2dbf0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2dc00 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2dc10 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2dc20 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2dc30 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2dc40 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2dc50 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2dc60 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2dc70 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2dc80 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2dc90 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2dca0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2dcb0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2dcc0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2dcd0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2dce0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2dcf0 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2dd00 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2dd10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2dd20 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2dd30 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2dd40 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2dd50 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2dd60 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2dd70 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2dd80 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2dd90 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2dda0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2ddb0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2ddc0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2ddd0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2dde0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2ddf0 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2de00 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2de10 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2de20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2de30 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2de40 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2de50 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2de60 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2de70 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2de80 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2de90 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2dea0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2deb0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2dec0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2ded0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2dee0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2def0 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2df00 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2df10 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2df20 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2df30 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2df40 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2df50 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2df60 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2df70 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2df80 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2df90 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2dfa0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2dfb0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2dfc0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2dfd0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2dfe0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2dff0 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2e000 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2e010 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2e020 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2e030 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
2e040 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2e050 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2e060 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2e070 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
2e080 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2e090 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2e0a0 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  t void *SQLITE_S
2e0b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
2e0c0 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
2e0d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2e0e0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2e0f0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
2e100 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
2e110 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e120 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
2e130 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2e140 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2e150 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2e160 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2e170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e180 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e190 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2e1a0 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2e1b0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2e1c0 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2e1d0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2e1e0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2e1f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2e200 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2e210 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2e220 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2e230 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2e240 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2e250 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2e260 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2e270 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2e280 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2e290 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2e2a0 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2e2b0 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2e2c0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2e2d0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2e2e0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2e2f0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2e300 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2e310 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2e320 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2e330 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2e340 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e350 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2e360 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2e370 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2e380 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2e390 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2e3a0 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2e3b0 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2e3c0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2e3d0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2e3e0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2e3f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2e400 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2e410 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2e420 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2e430 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2e440 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2e450 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2e460 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2e470 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2e480 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2e490 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2e4a0 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2e4b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2e4c0 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2e4d0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2e4e0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2e4f0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2e500 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2e510 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2e520 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2e530 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2e540 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2e550 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2e560 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2e570 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2e580 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2e590 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2e5a0 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2e5b0 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2e5c0 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2e5d0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2e5e0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2e5f0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2e600 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2e610 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2e620 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2e630 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2e640 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2e650 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2e660 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2e670 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2e680 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2e690 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2e6a0 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2e6b0 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2e6c0 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2e6d0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2e6e0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2e6f0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2e700 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2e710 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2e720 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2e730 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2e740 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2e750 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2e760 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2e770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2e780 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2e790 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2e7a0 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2e7b0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2e7c0 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2e7d0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2e7e0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2e7f0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2e800 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2e810 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2e820 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2e830 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2e840 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2e850 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2e860 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2e870 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2e880 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2e890 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2e8a0 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2e8b0 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2e8c0 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2e8d0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2e8e0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2e8f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2e900 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2e910 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2e920 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2e930 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2e940 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2e950 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2e960 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2e970 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2e980 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2e990 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2e9a0 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2e9b0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2e9c0 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2e9d0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2e9e0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2e9f0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2ea00 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2ea10 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ea20 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2ea30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ea40 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2ea50 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2ea60 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2ea70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2ea80 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2ea90 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2eaa0 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2eab0 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2eac0 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2ead0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2eae0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2eaf0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2eb00 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2eb10 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2eb20 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2eb30 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2eb40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2eb50 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2eb60 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2eb70 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2eb80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2eb90 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2eba0 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2ebb0 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2ebc0 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2ebd0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2ebe0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2ebf0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2ec00 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2ec10 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2ec20 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2ec30 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2ec40 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2ec50 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2ec60 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2ec70 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2ec80 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2ec90 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2eca0 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2ecb0 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2ecc0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2ecd0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2ece0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2ecf0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2ed00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2ed10 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2ed20 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2ed30 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2ed40 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2ed50 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2ed60 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2ed70 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2ed80 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2ed90 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2eda0 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2edb0 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2edc0 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2edd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2ede0 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2edf0 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2ee00 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2ee10 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2ee20 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ee30 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2ee40 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2ee50 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2ee60 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2ee70 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2ee80 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2ee90 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2eea0 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2eeb0 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2eec0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2eed0 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2eee0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2eef0 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2ef00 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2ef10 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2ef20 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2ef30 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2ef40 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2ef50 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2ef60 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2ef70 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2ef80 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2ef90 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2efa0 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2efb0 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2efc0 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2efd0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2efe0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2eff0 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2f000 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2f010 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2f020 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2f030 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2f040 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2f050 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2f060 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2f070 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2f080 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2f090 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2f0a0 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2f0b0 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2f0c0 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2f0d0 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2f0e0 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2f0f0 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2f100 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2f110 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2f120 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f130 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2f140 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2f150 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2f160 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2f170 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2f180 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2f190 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2f1a0 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2f1b0 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2f1c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2f1d0 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2f1e0 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2f1f0 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2f200 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2f210 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2f220 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
2f230 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2f240 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f250 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2f260 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2f270 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2f280 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2f290 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
2f2a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2f2b0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2f2c0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f2d0 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
2f2e0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f2f0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2f300 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
2f310 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
2f320 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
2f330 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2f340 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
2f350 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
2f360 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
2f370 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
2f380 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
2f390 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
2f3a0 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
2f3b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
2f3c0 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
2f3d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
2f3e0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
2f3f0 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
2f400 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f410 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
2f420 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
2f430 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
2f440 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
2f450 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f460 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
2f470 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
2f480 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
2f490 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2f4a0 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
2f4b0 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
2f4c0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2f4d0 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
2f4e0 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
2f4f0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2f500 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
2f510 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
2f520 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
2f530 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
2f540 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
2f550 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
2f560 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
2f570 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
2f580 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
2f590 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
2f5a0 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
2f5b0 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
2f5c0 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
2f5d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2f5e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
2f5f0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
2f600 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2f610 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61  DCALL sqlite3_da
2f620 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2f630 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2f640 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2f650 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2f660 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2f670 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2f680 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2f690 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2f6a0 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2f6b0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2f6c0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2f6d0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2f6e0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2f6f0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2f700 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2f710 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2f720 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2f730 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2f740 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2f750 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2f760 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2f770 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2f780 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2f790 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2f7a0 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2f7b0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2f7c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2f7d0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2f7e0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2f7f0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2f800 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2f810 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2f820 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2f830 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2f840 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2f850 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2f860 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2f870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2f880 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2f890 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2f8a0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2f8b0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2f8c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2f8d0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2f8e0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2f8f0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2f900 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2f910 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2f920 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2f930 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2f940 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2f950 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2f960 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2f970 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2f980 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2f990 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ions}.** METHOD:
2f9a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f9b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2f9c0 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  nes return infor
2f9d0 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73  mation about a s
2f9e0 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20  ingle column of 
2f9f0 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72  the current.** r
2fa00 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71  esult row of a q
2fa10 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79  uery.  ^In every
2fa20 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20   case the first 
2fa30 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
2fa40 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2fa50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fa60 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69  ent] that is bei
2fa70 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68  ng evaluated (th
2fa80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  e [sqlite3_stmt*
2fa90 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65  ].** that was re
2faa0 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  turned from [sql
2fab0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2fac0 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73  )] or one of its
2fad0 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e   variants).** an
2fae0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  d the second arg
2faf0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64  ument is the ind
2fb00 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  ex of the column
2fb10 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72   for which infor
2fb20 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  mation.** should
2fb30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54   be returned. ^T
2fb40 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2fb50 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2fb60 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64   set has the ind
2fb70 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75  ex 0..** ^The nu
2fb80 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2fb90 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61  in the result ca
2fba0 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
2fbb0 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2fbc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2fbd0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  ]..**.** If the 
2fbe0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
2fbf0 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  es not currently
2fc00 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69   point to a vali
2fc10 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65  d row, or if the
2fc20 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78  .** column index
2fc30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2fc40 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  , the result is 
2fc50 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
2fc60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79  ese routines may
2fc70 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20   only be called 
2fc80 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  when the most re
2fc90 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  cent call to.** 
2fca0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2fcb0 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53   has returned [S
2fcc0 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e  QLITE_ROW] and n
2fcd0 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2fce0 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20  e3_reset()] nor 
2fcf0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2fd00 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63  e()] have been c
2fd10 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74  alled subsequent
2fd20 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66  ly..** If any of
2fd30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2fd40 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72  are called after
2fd50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fd60 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2fd70 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
2fd80 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
2fd90 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
2fda0 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e  rned.** somethin
2fdb0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  g other than [SQ
2fdc0 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72  LITE_ROW], the r
2fdd0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2fde0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c  ined..** If [sql
2fdf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
2fe00 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2fe10 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2fe20 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65  nalize()].** are
2fe30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64   called from a d
2fe40 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20  ifferent thread 
2fe50 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65  while any of the
2fe60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61  se routines.** a
2fe70 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e  re pending, then
2fe80 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2fe90 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2fea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
2feb0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75  olumn_type() rou
2fec0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2fed0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2fee0 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63  GER | datatype c
2fef0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69  ode] for the ini
2ff00 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a  tial data type.*
2ff10 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  * of the result 
2ff20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65  column.  ^The re
2ff30 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20  turned value is 
2ff40 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
2ff50 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c  NTEGER],.** [SQL
2ff60 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c  ITE_FLOAT], [SQL
2ff70 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49  ITE_TEXT], [SQLI
2ff80 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51  TE_BLOB], or [SQ
2ff90 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65  LITE_NULL].  The
2ffa0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
2ffb0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2ffc0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f  lumn_type() is o
2ffd0 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69  nly meaningful i
2ffe0 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e  f no type.** con
2fff0 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63  versions have oc
30000 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69  curred as descri
30010 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65  bed below.  Afte
30020 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  r a type convers
30030 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75  ion,.** the valu
30040 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  e returned by sq
30050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
30060 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
30070 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72  .  Future.** ver
30080 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
30090 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62  may change the b
300a0 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74  ehavior of sqlit
300b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
300c0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
300d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e  type conversion.
300e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
300f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
30100 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20  or UTF-8 string 
30110 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
30120 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a  _column_bytes().
30130 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
30140 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
30150 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
30160 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
30170 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30180 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72   is a UTF-16 str
30190 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
301a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
301b0 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
301c0 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38   string to UTF-8
301d0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
301e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
301f0 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
30200 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
30210 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
30220 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30230 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20  bytes() uses.** 
30240 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
30250 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
30260 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
30270 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64  UTF-8 string and
30280 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
30290 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
302a0 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
302b0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
302c0 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
302d0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
302e0 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a  ytes() returns z
302f0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ero..**.** ^If t
30300 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
30310 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74  LOB or UTF-16 st
30320 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
30330 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30340 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  es16().** routin
30350 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
30360 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30370 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
30380 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
30390 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
303a0 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  -8 string, then 
303b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
303c0 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74  ytes16() convert
303d0 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
303e0 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68  to UTF-16 and th
303f0 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
30400 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
30410 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
30420 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
30430 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
30440 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30450 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
30460 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
30470 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
30480 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31  value to a UTF-1
30490 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  6 string and ret
304a0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
304b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
304c0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
304d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
304e0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
304f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30500 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  16() returns zer
30510 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61  o..**.** ^The va
30520 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
30530 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30540 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a  _bytes()] and .*
30550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30560 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20  n_bytes16()] do 
30570 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20  not include the 
30580 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73  zero terminators
30590 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f   at the end.** o
305a0 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e  f the string.  ^
305b0 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65  For clarity: the
305c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
305d0 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
305e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
305f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  and [sqlite3_col
30600 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61  umn_bytes16()] a
30610 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  re the number of
30620 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65  .** bytes in the
30630 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65   string, not the
30640 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
30650 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74  cters..**.** ^St
30660 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
30670 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30680 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69  _text() and sqli
30690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
306a0 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70  6(),.** even emp
306b0 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20  ty strings, are 
306c0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
306d0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65  inated.  ^The re
306e0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72  turn.** value fr
306f0 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  om sqlite3_colum
30700 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a  n_blob() for a z
30710 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20  ero-length BLOB 
30720 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
30730 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e  r..**.** <b>Warn
30740 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62  ing:</b> ^The ob
30750 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
30760 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30770 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a  _value()] is an.
30780 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
30790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
307a0 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c  bject.  In a mul
307b0 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72  tithreaded envir
307c0 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e  onment,.** an un
307d0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
307e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
307f0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
30800 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b  safely with.** [
30810 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
30820 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
30830 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30840 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
30850 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
30860 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
30870 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
30880 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30890 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
308a0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
308b0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
308c0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
308d0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
308e0 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
308f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30900 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
30910 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
30920 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f  ()], the behavio
30930 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73  r is not threads
30940 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  afe..**.** These
30950 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
30960 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
30970 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
30980 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
30990 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
309a0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
309b0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
309c0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
309d0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
309e0 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
309f0 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
30a00 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
30a10 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
30a20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
30a30 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
30a40 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
30a50 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
30a60 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
30a70 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
30a80 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
30a90 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
30aa0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
30ab0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
30ac0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
30ad0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
30ae0 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
30af0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
30b00 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
30b10 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
30b20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
30b30 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
30b40 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
30b50 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
30b60 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
30b70 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
30b80 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61  <td> Result is a
30b90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
30ba0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30bb0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30bc0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30bd0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
30be0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
30bf0 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  GER  <td>  FLOAT
30c00 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
30c10 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f   from integer to
30c20 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
30c30 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
30c40 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
30c50 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20  ASCII rendering 
30c60 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a  of the integer.*
30c70 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30c80 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  ER  <td>   BLOB 
30c90 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
30ca0 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a  INTEGER->TEXT.**
30cb0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
30cc0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
30cd0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
30ce0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
30cf0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
30d00 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
30d10 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
30d20 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
30d30 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
30d40 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
30d50 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30d60 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74  o BLOB.** <tr><t
30d70 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
30d80 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
30d90 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
30da0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  R.** <tr><td>  T
30db0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
30dc0 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
30dd0 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
30de0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30df0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30e00 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30e10 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30e20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30e30 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30e40 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
30e50 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30e60 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30e70 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
30e80 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30e90 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  B    <td>   TEXT
30ea0 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a      <td> Add a z
30eb0 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69  ero terminator i
30ec0 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61  f needed.** </ta
30ed0 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71  ble>.** </blockq
30ee0 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  uote>)^.**.** No
30ef0 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70  te that when typ
30f00 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63  e conversions oc
30f10 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65  cur, pointers re
30f20 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a  turned by prior.
30f30 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
30f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30f50 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ), sqlite3_colum
30f60 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72  n_text(), and/or
30f70 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30f80 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20  mn_text16() may 
30f90 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  be invalidated..
30fa0 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69  ** Type conversi
30fb0 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20  ons and pointer 
30fc0 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69  invalidations mi
30fd0 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ght occur.** in 
30fe0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61  the following ca
30ff0 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ses:.**.** <ul>.
31000 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
31010 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61  ial content is a
31020 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65   BLOB and sqlite
31030 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
31040 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
31050 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31060 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41  () is called.  A
31070 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
31080 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e   might.**      n
31090 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20  eed to be added 
310a0 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f  to the string.</
310b0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
310c0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
310d0 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e  is UTF-8 text an
310e0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
310f0 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a  _bytes16() or.**
31100 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
31110 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
31120 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
31130 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
31140 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
31150 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a  to UTF-16.</li>.
31160 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74  ** <li> The init
31170 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55  ial content is U
31180 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73  TF-16 text and s
31190 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
311a0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  tes() or.**     
311b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
311c0 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64  text() is called
311d0 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d  .  The content m
311e0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
311f0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d  .**      to UTF-
31200 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  8.</li>.** </ul>
31210 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69  .**.** ^Conversi
31220 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d  ons between UTF-
31230 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c  16be and UTF-16l
31240 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e  e are always don
31250 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64  e in place and d
31260 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64  o.** not invalid
31270 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e  ate a prior poin
31280 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63  ter, though of c
31290 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e  ourse the conten
312a0 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a  t of the buffer.
312b0 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f  ** that the prio
312c0 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65  r pointer refere
312d0 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62  nces will have b
312e0 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f  een modified.  O
312f0 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66  ther kinds.** of
31300 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20   conversion are 
31310 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68  done in place wh
31320 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c  en it is possibl
31330 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73  e, but sometimes
31340 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74   they.** are not
31350 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e   possible and in
31360 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69   those cases pri
31370 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20  or pointers are 
31380 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a  invalidated..**.
31390 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f  ** The safest po
313a0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
313b0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
313c0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
313d0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
313e0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
313f0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
31400 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
31410 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
31420 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
31430 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
31440 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
31450 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
31460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31470 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
31480 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
31490 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
314a0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
314b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
314c0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
314d0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
314e0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
314f0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
31500 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
31510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
31520 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
31530 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
31540 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
31550 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
31560 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
31570 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
31580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31590 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
315a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
315b0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
315c0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
315d0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
315e0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
315f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31600 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
31610 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
31620 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
31630 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31640 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
31650 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
31660 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31670 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
31680 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31690 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
316a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
316b0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
316c0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
316d0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
316e0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
316f0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
31700 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
31710 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
31720 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
31730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
31740 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
31750 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
31760 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
31770 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
31780 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
31790 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
317a0 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e   Do <em>not</em>
317b0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
317c0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66  rs returned.** f
317d0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
317e0 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
317f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31800 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
31810 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
31820 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
31830 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
31840 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
31850 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
31860 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
31870 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
31880 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
31890 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
318a0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
318b0 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
318c0 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
318d0 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
318e0 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
318f0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
31900 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
31910 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
31920 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
31930 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
31940 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
31950 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
31960 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
31970 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31980 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
31990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
319a0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
319b0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
319c0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
319d0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
319e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
319f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31a00 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
31a10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31a20 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
31a30 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75  ;.SQLITE_API dou
31a50 62 6c 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ble SQLITE_STDCA
31a60 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
31a70 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
31a80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31a90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
31aa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
31ab0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31ac0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
31ad0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31ae0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
31af0 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
31b00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
31b10 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
31b20 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31b30 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31b40 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
31b50 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
31b60 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
31b70 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
31b80 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31b90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31ba0 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
31bb0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
31bc0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
31bd0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31be0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31bf0 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
31c00 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
31c10 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65  lumn_type(sqlite
31c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31c30 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
31c40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53 51  qlite3_value *SQ
31c50 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
31c60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
31c70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
31c80 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
31c90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
31ca0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
31cb0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
31cc0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
31cd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31ce0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
31cf0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
31d00 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
31d10 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
31d20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
31d30 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
31d40 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
31d50 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
31d60 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
31d70 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
31d80 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
31d90 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
31da0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
31db0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31dc0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
31dd0 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
31de0 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
31df0 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
31e00 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
31e10 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
31e20 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
31e30 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
31e40 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
31e50 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
31e60 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
31e70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
31e80 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
31e90 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
31ea0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
31eb0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
31ec0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
31ed0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31ee0 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
31ef0 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
31f00 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
31f10 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
31f20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
31f30 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
31f40 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
31f50 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
31f60 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
31f70 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
31f80 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
31f90 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
31fa0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
31fb0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
31fc0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
31fd0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
31fe0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
31ff0 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
32000 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
32010 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
32020 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32030 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
32040 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
32050 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
32060 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
32070 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
32080 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
32090 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
320a0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
320b0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
320c0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
320d0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
320e0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
320f0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
32100 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
32110 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
32120 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
32130 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
32140 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
32150 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
32160 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
32170 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
32180 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 69 6e  CALL sqlite3_fin
32190 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74  alize(sqlite3_st
321a0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
321b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
321c0 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74  et A Prepared St
321d0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
321e0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
321f0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65  3_stmt.**.** The
32200 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
32210 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
32220 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
32230 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32240 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
32250 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
32260 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
32270 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
32280 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
32290 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
322a0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
322b0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
322c0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
322d0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
322e0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
322f0 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
32300 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
32310 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
32320 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
32330 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
32340 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
32350 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32360 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
32370 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
32380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
32390 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
323a0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
323b0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
323c0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
323d0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
323e0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
323f0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
32400 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
32410 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
32420 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
32430 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
32440 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
32450 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
32460 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
32470 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
32480 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
32490 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
324a0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
324b0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
324c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
324d0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
324e0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
324f0 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
32500 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
32510 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
32520 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
32530 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
32540 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
32550 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
32560 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
32570 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
32580 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
32590 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
325a0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
325b0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
325c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
325d0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
325e0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
325f0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
32600 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
32610 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
32620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
32630 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
32640 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
32650 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
32660 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
32670 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
32680 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
32690 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
326a0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
326b0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
326c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
326d0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
326e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
326f0 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
32700 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
32710 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
32720 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
32730 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
32740 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
32750 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
32760 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
32770 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
32780 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
32790 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
327a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
327b0 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
327c0 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
327d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
327e0 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
327f0 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
32800 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
32810 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
32820 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
32830 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
32840 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
32850 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
32860 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
32870 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
32880 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
32890 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
328a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
328b0 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
328c0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
328d0 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
328e0 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
328f0 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
32900 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
32910 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
32920 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
32930 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
32940 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
32950 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
32960 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
32970 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
32980 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
32990 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
329a0 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
329b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
329c0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
329d0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
329e0 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
329f0 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
32a00 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
32a10 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
32a20 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
32a30 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
32a40 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
32a50 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
32a60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
32a70 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
32a80 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
32a90 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
32aa0 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
32ab0 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
32ac0 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
32ad0 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
32ae0 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
32af0 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
32b00 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
32b10 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
32b20 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
32b30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
32b40 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
32b50 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
32b60 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
32b70 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
32b80 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32b90 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
32ba0 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
32bb0 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
32bc0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32bd0 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
32be0 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
32bf0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
32c00 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
32c10 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
32c20 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
32c30 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
32c40 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
32c50 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
32c60 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
32c70 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
32c80 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
32c90 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
32ca0 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
32cb0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
32cc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32cd0 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
32ce0 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
32cf0 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
32d00 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
32d10 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
32d20 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
32d30 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
32d40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
32d50 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
32d60 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
32d70 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
32d80 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
32d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
32da0 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
32db0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
32dc0 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
32dd0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
32de0 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
32df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32e00 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
32e10 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
32e20 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
32e30 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
32e40 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
32e50 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
32e60 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
32e70 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
32e80 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
32e90 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
32ea0 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
32eb0 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
32ec0 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
32ed0 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
32ee0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
32ef0 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
32f00 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
32f10 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
32f20 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
32f30 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
32f40 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32f50 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
32f60 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
32f70 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
32f80 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
32f90 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
32fa0 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
32fb0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
32fc0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
32fd0 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
32fe0 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
32ff0 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
33000 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
33010 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
33020 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
33030 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
33040 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
33050 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
33060 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
33070 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
33080 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
33090 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
330a0 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
330b0 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
330c0 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
330d0 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
330e0 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
330f0 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
33100 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
33110 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
33120 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
33130 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
33140 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
33150 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
33160 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
33170 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
33180 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
33190 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
331a0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
331b0 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
331c0 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
331d0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
331e0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
331f0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
33200 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
33210 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
33220 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
33230 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
33240 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33250 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
33260 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
33270 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
33280 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
33290 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
332a0 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
332b0 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
332c0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
332d0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
332e0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
332f0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
33300 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
33310 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
33320 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
33330 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
33340 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
33350 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
33360 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
33370 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
33380 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
33390 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
333a0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
333b0 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
333c0 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
333d0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
333e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
333f0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
33400 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
33410 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
33420 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
33430 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
33440 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
33450 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
33460 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
33470 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
33480 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
33490 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
334a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
334b0 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
334c0 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
334d0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
334e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
334f0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
33500 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
33510 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
33520 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
33530 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
33540 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
33550 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
33560 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
33570 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
33580 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
33590 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
335a0 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
335b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
335c0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
335d0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
335e0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
335f0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
33600 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
33610 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
33620 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
33630 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
33640 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
33650 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33660 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
33670 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
33680 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
33690 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
336a0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
336b0 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
336c0 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
336d0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
336e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
336f0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
33700 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
33710 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
33720 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
33730 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
33740 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
33750 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
33760 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
33770 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
33780 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
33790 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
337a0 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
337b0 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
337c0 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
337d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
337e0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
337f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
33800 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
33810 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
33820 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
33830 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
33840 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
33850 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
33860 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
33870 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
33880 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
33890 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
338a0 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
338b0 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
338c0 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
338d0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
338e0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
338f0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
33900 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
33910 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
33920 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
33930 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
33940 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
33950 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
33960 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
33970 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
33980 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
33990 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
339a0 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
339b0 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
339c0 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
339d0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
339e0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
339f0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
33a00 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
33a10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
33a20 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
33a30 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
33a40 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
33a50 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
33a60 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
33a70 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
33a80 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
33a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
33aa0 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
33ab0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
33ac0 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
33ad0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
33ae0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
33af0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33b00 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
33b10 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33b20 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
33b30 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
33b40 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
33b50 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
33b60 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
33b70 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
33b80 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
33b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33ba0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33bb0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
33bc0 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
33bd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33be0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33bf0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
33c00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
33c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
33c20 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
33c30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33c40 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c  unction16(.  sql
33c50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
33c60 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f  t void *zFunctio
33c70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
33c80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
33c90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
33ca0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
33cb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33cc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
33cd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
33ce0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
33cf0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
33d00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
33d10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
33d20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33d30 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
33d40 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
33d50 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
33d60 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
33d70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
33d80 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
33d90 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
33da0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33db0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33dc0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33dd0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33de0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33df0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33e00 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33e10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33e20 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33e30 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
33e40 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
33e50 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
33e60 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
33e70 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33e80 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
33e90 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
33ea0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
33eb0 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
33ec0 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
33ed0 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
33ee0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
33ef0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
33f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33f10 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
33f20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33  1    /* IMP: R-3
33f30 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64  7514-35566 */.#d
33f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33f50 31 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20  16LE        2   
33f60 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31   /* IMP: R-03371
33f70 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e  -37637 */.#defin
33f80 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
33f90 20 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20          3    /* 
33fa0 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31  IMP: R-51971-341
33fb0 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  54 */.#define SQ
33fc0 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
33fd0 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
33fe0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
33ff0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
34000 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
34010 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65     5    /* Depre
34020 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  cated */.#define
34030 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c   SQLITE_UTF16_AL
34040 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73  IGNED  8    /* s
34050 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34060 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a  llation only */.
34070 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34080 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a   Function Flags.
34090 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
340a0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65  tants may be ORe
340b0 64 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20  d together with 
340c0 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
340d0 55 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64  UTF8 | preferred
340e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
340f0 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  as the fourth ar
34100 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71  gument.** to [sq
34110 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
34120 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ction()], [sqlit
34130 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34140 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
34150 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34160 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  unction_v2()]..*
34170 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
34180 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20  _DETERMINISTIC  
34190 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43    0x800../*.** C
341a0 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
341b0 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
341c0 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
341d0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
341e0 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
341f0 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
34200 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
34210 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
34220 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
34230 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
34240 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
34250 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
34260 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
34270 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
34280 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
34290 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
342a0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65  functions.  To e
342b0 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d  ncourage program
342c0 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  mers to avoid.**
342d0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
342e0 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78  , we will not ex
342f0 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20  plain what they 
34300 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
34310 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
34320 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
34330 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
34340 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  ED int SQLITE_ST
34350 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 61 67  DCALL sqlite3_ag
34360 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
34370 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34380 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
34390 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
343a0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
343b0 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64   sqlite3_expired
343c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
343d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
343e0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
343f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
34400 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65   sqlite3_transfe
34410 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
34420 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65  e3_stmt*, sqlite
34430 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
34440 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
34450 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
34460 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
34470 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
34480 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
34490 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
344a0 41 54 45 44 20 76 6f 69 64 20 53 51 4c 49 54 45  ATED void SQLITE
344b0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
344c0 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
344d0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
344e0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
344f0 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  TED int SQLITE_S
34500 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d  TDCALL sqlite3_m
34510 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
34520 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
34530 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
34540 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
34550 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
34560 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
34570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34580 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
34590 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  Values.** METHOD
345a0 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a  : sqlite3_value.
345b0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
345c0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
345d0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
345e0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
345f0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
34600 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
34610 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
34620 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
34630 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
34640 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
34650 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a 0a  aggregate.  .**.
34660 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f  ** The xFunc (fo
34670 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f  r scalar functio
34680 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f  ns) or xStep (fo
34690 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61  r aggregates) pa
346a0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b  rameters.** to [
346b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
346c0 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  unction()] and [
346d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
346e0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20  unction16()].** 
346f0 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73  define callbacks
34700 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
34710 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
34720 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34730 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72  ..** The 3rd par
34740 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20  ameter to these 
34750 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20  callbacks is an 
34760 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
34770 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74  s to.** [protect
34780 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
34790 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72  ] objects.  Ther
347a0 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65  e is one [sqlite
347b0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
347c0 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61  for.** each para
347d0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c  meter to the SQL
347e0 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73   function.  Thes
347f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
34800 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63  sed to.** extrac
34810 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68  t values from th
34820 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34830 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a  ] objects..**.**
34840 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34850 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b  work only with [
34860 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34870 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
34880 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
34890 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f   to use these ro
348a0 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e  utines on an [un
348b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
348c0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65  3_value].** obje
348d0 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e  ct results in un
348e0 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
348f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
34900 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73  outines work jus
34910 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65  t like the corre
34920 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e  sponding [column
34930 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
34940 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  s].** except tha
34950 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  t these routines
34960 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
34970 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34980 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
34990 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
349a0 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
349b0 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
349c0 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
349d0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
349e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
349f0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
34a00 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
34a10 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
34a20 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
34a30 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
34a40 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
34a50 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
34a60 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
34a70 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
34a80 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
34a90 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
34aa0 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
34ab0 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
34ac0 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
34ad0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
34ae0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
34af0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34b00 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
34b10 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
34b20 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
34b30 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
34b40 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
34b50 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
34b60 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
34b70 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
34b80 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
34b90 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
34ba0 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
34bb0 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
34bc0 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
34bd0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
34be0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
34bf0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
34c00 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
34c10 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
34c20 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
34c30 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
34c40 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
34c50 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
34c60 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
34c70 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
34c80 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
34c90 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
34ca0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
34cb0 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
34cc0 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
34cd0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
34ce0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
34cf0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
34d00 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
34d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
34d20 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
34d30 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
34d40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
34d50 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
34d60 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
34d70 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
34d80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
34d90 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
34da0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
34db0 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
34dc0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
34dd0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
34de0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34df0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
34e00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
34e10 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
34e20 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
34e30 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
34e40 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
34e50 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
34e60 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
34e70 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  eters..*/.SQLITE
34e80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
34e90 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
34ea0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
34eb0 6f 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ob(sqlite3_value
34ec0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
34ed0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
34ee0 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  L sqlite3_value_
34ef0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
34f00 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34f10 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
34f20 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
34f30 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
34f40 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
34f50 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 53 51  TE_API double SQ
34f60 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34f70 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
34f80 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34f90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
34fa0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
34fb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
34fc0 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt(sqlite3_value
34fd0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  *);.SQLITE_API s
34fe0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
34ff0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35000 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
35010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35020 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
35030 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
35040 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
35050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35060 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
35070 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
35080 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
35090 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
350a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
350b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
350c0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
350d0 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
350e0 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
350f0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
35100 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
35110 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
35120 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
35130 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
35140 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
35150 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
35160 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
35170 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35180 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c  3_value_type(sql
35190 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
351a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
351b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
351c0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
351d0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
351e0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
351f0 41 50 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67  API3REF: Finding
35200 20 54 68 65 20 53 75 62 74 79 70 65 20 4f 66 20   The Subtype Of 
35210 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
35220 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
35230 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  lue.**.** The sq
35240 6c 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74  lite3_value_subt
35250 79 70 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20  ype(V) function 
35260 72 65 74 75 72 6e 73 20 74 68 65 20 73 75 62 74  returns the subt
35270 79 70 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61  ype for.** an [a
35280 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35290 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
352a0 20 61 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68   argument V.  Th
352b0 65 20 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66  e subtype.** inf
352c0 6f 72 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20  ormation can be 
352d0 75 73 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c  used to pass a l
352e0 69 6d 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66  imited amount of
352f0 20 63 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a   context from.**
35300 20 6f 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   one SQL functio
35310 6e 20 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55  n to another.  U
35320 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  se the [sqlite3_
35330 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29  result_subtype()
35340 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  ].** routine to 
35350 73 65 74 20 74 68 65 20 73 75 62 74 79 70 65 20  set the subtype 
35360 66 6f 72 20 74 68 65 20 72 65 74 75 72 6e 20 76  for the return v
35370 61 6c 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66  alue of an SQL f
35380 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53  unction..**.** S
35390 51 4c 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75  QLite makes no u
353a0 73 65 20 6f 66 20 73 75 62 74 79 70 65 20 69 74  se of subtype it
353b0 73 65 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79  self.  It merely
353c0 20 70 61 73 73 65 73 20 74 68 65 20 73 75 62 74   passes the subt
353d0 79 70 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ype.** from the 
353e0 72 65 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61  result of one [a
353f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35400 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  ed SQL function]
35410 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70   into the.** inp
35420 75 74 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a  ut of another..*
35430 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 75 6e 73  /.SQLITE_API uns
35440 69 67 6e 65 64 20 69 6e 74 20 53 51 4c 49 54 45  igned int SQLITE
35450 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35460 5f 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73  _value_subtype(s
35470 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35480 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35490 20 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53   Copy And Free S
354a0 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
354b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
354c0 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ue.**.** ^The sq
354d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
354e0 56 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b  V) interface mak
354f0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
35500 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
35510 0a 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64  .** object D and
35520 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
35530 65 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e  er to that copy.
35540 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f    ^The [sqlite3_
35550 76 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a  value] returned.
35560 2a 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74  ** is a [protect
35570 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35580 5d 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66  ] object even if
35590 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f   the input is no
355a0 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
355b0 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20  e3_value_dup(V) 
355c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
355d0 73 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e  s NULL if V is N
355e0 55 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d  ULL or if a.** m
355f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
35600 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54   fails..**.** ^T
35610 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
35620 5f 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61  _free(V) interfa
35630 63 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c  ce frees an [sql
35640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
35650 63 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ct.** previously
35660 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
35670 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
35680 70 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20  p()].  ^If V is 
35690 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
356a0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76  * then sqlite3_v
356b0 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20  alue_free(V) is 
356c0 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
356d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
356e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53  sqlite3_value *S
356f0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35700 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
35710 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
35720 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
35730 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54  I void SQLITE_ST
35740 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
35750 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
35760 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
35770 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
35780 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
35790 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
357a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
357b0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
357c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
357d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
357e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
357f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
35800 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
35810 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
35820 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
35830 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
35840 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
35850 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35860 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
35870 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
35880 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
35890 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
358a0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
358b0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
358c0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
358d0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
358e0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
358f0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
35900 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
35910 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
35920 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
35930 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35940 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
35950 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
35960 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
35970 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
35980 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
35990 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
359a0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
359b0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
359c0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
359d0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
359e0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
359f0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
35a00 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
35a10 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
35a20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
35a30 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
35a40 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
35a50 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
35a60 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
35a70 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
35a80 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
35a90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
35aa0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
35ab0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
35ac0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
35ad0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
35ae0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
35af0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
35b00 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
35b10 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
35b20 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
35b30 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
35b40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35b50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35b60 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
35b70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
35b80 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
35b90 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
35ba0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
35bb0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
35bc0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
35bd0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
35be0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
35bf0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
35c00 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
35c10 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
35c20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35c30 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
35c40 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
35c50 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
35c60 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
35c70 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
35c80 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
35c90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35ca0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
35cb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
35cc0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
35cd0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
35ce0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
35cf0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
35d00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
35d10 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
35d20 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
35d30 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
35d40 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
35d50 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
35d60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35d70 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
35d80 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
35d90 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
35da0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
35db0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
35dc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
35dd0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
35de0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
35df0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35e00 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
35e10 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
35e20 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
35e30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
35e40 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
35e50 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
35e60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
35e70 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
35e80 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
35e90 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
35ea0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
35eb0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
35ec0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
35ed0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
35ee0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
35ef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
35f00 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35f10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35f20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35f30 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35f40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
35f50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35f60 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35f70 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
35f80 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
35f90 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35fa0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
35fb0 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65  text*, int nByte
35fc0 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
35fd0 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20 46  REF: User Data F
35fe0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
35ff0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
36000 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
36010 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
36020 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
36030 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
36040 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
36050 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
36060 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
36070 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
36080 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
36090 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
360a0 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
360b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
360c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
360d0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
360e0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
360f0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
36100 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
36110 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
36120 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
36130 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36140 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36150 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
36160 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36170 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
36180 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
36190 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
361a0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
361b0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
361c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
361d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
361e0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
361f0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
36200 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
36210 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
36220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36230 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
36240 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
36250 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
36260 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
36270 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
36280 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36290 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
362a0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
362b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
362c0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
362d0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
362e0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
362f0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
36300 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
36310 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
36320 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
36330 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
36340 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 53  E_API sqlite3 *S
36350 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
36370 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
36380 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
36390 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
363a0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
363b0 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
363c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
363d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
363e0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
363f0 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
36400 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
36410 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
36420 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
36430 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
36440 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
36450 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
36460 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
36470 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
36480 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
36490 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
364a0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
364b0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
364c0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
364d0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
364e0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
364f0 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
36500 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
36510 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
36520 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
36530 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
36540 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
36550 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
36560 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
36570 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
36580 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
36590 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
365a0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
365b0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
365c0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
365d0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
365e0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
365f0 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
36600 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
36610 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
36620 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
36630 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
36640 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
36650 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
36660 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
36670 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
36680 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
36690 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
366a0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
366b0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
366c0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
366d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
366e0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
366f0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
36700 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36710 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
36720 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
36730 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
36740 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
36750 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
36760 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
36770 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
36780 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
36790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
367a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
367b0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
367c0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
367d0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
367e0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
367f0 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
36800 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36810 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36820 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
36830 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
36840 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
36850 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
36860 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
36870 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
36880 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
36890 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
368a0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
368b0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
368c0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
368d0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
368e0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
368f0 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
36900 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36910 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
36920 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
36930 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
36940 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
36950 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
36960 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
36970 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
36980 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
36990 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
369a0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
369b0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
369c0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
369d0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
369e0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
369f0 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
36a00 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
36a10 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
36a20 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
36a30 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
36a40 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
36a50 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
36a60 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
36a70 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
36a80 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
36a90 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
36aa0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
36ab0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
36ac0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
36ad0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
36ae0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
36af0 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
36b00 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
36b10 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
36b20 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
36b30 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
36b40 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
36b50 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
36b60 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
36b70 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
36b80 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
36b90 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
36ba0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
36bb0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
36bc0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
36bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
36be0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
36bf0 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
36c00 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
36c10 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
36c20 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
36c30 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
36c40 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
36c50 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
36c60 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
36c70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
36c80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
36c90 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
36ca0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
36cb0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
36cc0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
36cd0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
36ce0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
36cf0 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
36d00 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
36d10 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
36d20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
36d30 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
36d40 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
36d50 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
36d60 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
36d70 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
36d80 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
36d90 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
36da0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
36db0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
36dc0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36dd0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
36de0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
36df0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
36e00 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
36e10 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
36e20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36e30 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69  get_auxdata(sqli
36e40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
36e50 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t N);.SQLITE_API
36e60 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44   void SQLITE_STD
36e70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74  CALL sqlite3_set
36e80 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
36e90 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
36ea0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
36eb0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
36ec0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
36ed0 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
36ee0 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
36ef0 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
36f00 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
36f10 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
36f20 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
36f30 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
36f40 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
36f50 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
36f60 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
36f70 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
36f80 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
36f90 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
36fa0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
36fb0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
36fc0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
36fd0 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
36fe0 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
36ff0 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
37000 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
37010 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
37020 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
37030 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
37040 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
37050 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
37060 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
37070 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
37080 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
37090 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
370a0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
370b0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
370c0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
370d0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
370e0 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
370f0 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
37100 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
37110 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
37120 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65  mpilers..*/.type
37130 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
37140 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
37150 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
37160 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
37170 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
37180 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
37190 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
371a0 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
371b0 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
371c0 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
371d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
371e0 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
371f0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
37200 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ion.** METHOD: s
37210 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
37220 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
37230 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20  nes are used by 
37240 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69  the xFunc or xFi
37250 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68  nal callbacks th
37260 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20  at.** implement 
37270 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
37280 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53  d aggregates.  S
37290 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ee.** [sqlite3_c
372a0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
372b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
372c0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
372d0 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74  ()].** for addit
372e0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
372f0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  n..**.** These f
37300 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65  unctions work ve
37310 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65  ry much like the
37320 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64   [parameter bind
37330 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  ing] family of.*
37340 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64  * functions used
37350 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20   to bind values 
37360 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  to host paramete
37370 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73  rs in prepared s
37380 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65  tatements..** Re
37390 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20  fer to the [SQL 
373a0 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d  parameter] docum
373b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
373c0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
373d0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
373e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
373f0 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20  lob() interface 
37400 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
37410 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
37420 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37430 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
37440 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e  e BLOB whose con
37450 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a  tent is pointed.
37460 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63  ** to by the sec
37470 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  ond parameter an
37480 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74  d which is N byt
37490 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20  es long where N 
374a0 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20  is the.** third 
374b0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
374c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
374d0 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c  sult_zeroblob(C,
374e0 4e 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  N) and sqlite3_r
374f0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34  esult_zeroblob64
37500 28 43 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61  (C,N).** interfa
37510 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75  ces set the resu
37520 6c 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  lt of the applic
37530 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37540 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
37550 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e  a BLOB containin
37560 67 20 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73  g all zero bytes
37570 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
37580 73 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  size..**.** ^The
37590 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
375a0 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61  double() interfa
375b0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
375c0 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
375d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
375e0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
375f0 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
37600 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65  t value specifie
37610 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20  d.** by its 2nd 
37620 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
37630 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37640 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
37650 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37660 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f  rror16() functio
37670 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20  ns.** cause the 
37680 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20  implemented SQL 
37690 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f  function to thro
376a0 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a  w an exception..
376b0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
376c0 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  the string point
376d0 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20  ed to by the.** 
376e0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
376f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37700 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74  error() or sqlit
37710 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37720 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65  6().** as the te
37730 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d  xt of an error m
37740 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65  essage.  ^SQLite
37750 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
37760 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
37770 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
37780 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37790 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53  r() as UTF-8. ^S
377a0 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72  QLite.** interpr
377b0 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66  ets the string f
377c0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
377d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20  lt_error16() as 
377e0 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65  UTF-16 in native
377f0 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20  .** byte order. 
37800 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
37810 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37820 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37830 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37840 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37850 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68  ) is negative th
37860 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
37870 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  as the error.** 
37880 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74  message all text
37890 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20   up through the 
378a0 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
378b0 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
378c0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
378d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
378e0 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a  lt_error() or.**
378f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37900 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e  error16() is non
37910 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53  -negative then S
37920 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74  QLite takes that
37930 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28   many.** bytes (
37940 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
37950 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
37960 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72  ameter as the er
37970 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20  ror message..** 
37980 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37990 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20  ult_error() and 
379a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
379b0 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74  rror16().** rout
379c0 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76  ines make a priv
379d0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
379e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65  error message te
379f0 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  xt before.** the
37a00 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65  y return.  Hence
37a10 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75  , the calling fu
37a20 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c  nction can deall
37a30 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69  ocate or.** modi
37a40 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65  fy the text afte
37a50 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69  r they return wi
37a60 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
37a70 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37a80 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20  lt_error_code() 
37a90 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73  function changes
37aa0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a   the error code.
37ab0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53  ** returned by S
37ac0 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c  QLite as a resul
37ad0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e  t of an error in
37ae0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42   a function.  ^B
37af0 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68  y default,.** th
37b00 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
37b10 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e  SQLITE_ERROR.  ^
37b20 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  A subsequent cal
37b30 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  l to sqlite3_res
37b40 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
37b50 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
37b60 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74  _error16() reset
37b70 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37b80 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   to SQLITE_ERROR
37b90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37ba0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37bb0 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72  r_toobig() inter
37bc0 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37bd0 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37be0 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37bf0 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67  ng that a string
37c00 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20   or BLOB is too 
37c10 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e  long to represen
37c20 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
37c30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37c40 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72  or_nomem() inter
37c50 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69  face causes SQLi
37c60 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a  te to throw an.*
37c70 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69  * error indicati
37c80 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79  ng that a memory
37c90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
37ca0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
37cb0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
37cc0 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  t() interface se
37cd0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
37ce0 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
37cf0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37d00 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37d10 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e   the 32-bit sign
37d20 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
37d30 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
37d40 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
37d50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37d60 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e  esult_int64() in
37d70 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
37d80 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
37d90 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
37da0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37db0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36  tion to be the 6
37dc0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
37dd0 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69  eger.** value gi
37de0 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61  ven in the 2nd a
37df0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
37e00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37e10 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66  lt_null() interf
37e20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37e30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37e40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37e50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37e60 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a   to be NULL..**.
37e70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37e80 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73  result_text(), s
37e90 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37ea0 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  xt16(),.** sqlit
37eb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37ec0 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65  le(), and sqlite
37ed0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
37ee0 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
37ef0 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e  * set the return
37f00 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70   value of the ap
37f10 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37f20 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
37f30 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e  .** a text strin
37f40 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65  g which is repre
37f50 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c  sented as UTF-8,
37f60 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62   UTF-16 native b
37f70 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54  yte order,.** UT
37f80 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69  F-16 little endi
37f90 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69  an, or UTF-16 bi
37fa0 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63  g endian, respec
37fb0 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20  tively..** ^The 
37fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37fd0 65 78 74 36 34 28 29 20 69 6e 74 65 72 66 61 63  ext64() interfac
37fe0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
37ff0 6e 20 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a  n value of an.**
38000 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
38010 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
38020 20 62 65 20 61 20 74 65 78 74 20 73 74 72 69 6e   be a text strin
38030 67 20 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67  g in an encoding
38040 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 62 79  .** specified by
38050 20 74 68 65 20 66 69 66 74 68 20 28 61 6e 64 20   the fifth (and 
38060 6c 61 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c  last) parameter,
38070 20 77 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f   which must be o
38080 6e 65 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45  ne.** of [SQLITE
38090 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
380a0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
380b0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
380c0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a  LITE_UTF16LE]..*
380d0 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
380e0 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
380f0 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
38100 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
38110 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
38120 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
38130 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
38140 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
38150 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
38160 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
38170 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
38180 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
38190 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
381a0 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
381b0 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
381c0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
381d0 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
381e0 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
381f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
38200 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
38210 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38220 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
38230 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
38240 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
38250 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
38260 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
38270 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
38280 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
38290 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
382a0 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
382b0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
382c0 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
382d0 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
382e0 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
382f0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
38300 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
38310 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
38320 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
38330 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
38340 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
38350 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
38360 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
38370 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
38380 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
38390 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
383a0 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
383b0 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
383c0 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
383d0 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
383e0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
383f0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
38400 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
38410 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
38420 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
38430 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
38440 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
38450 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
38460 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
38470 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
38480 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
38490 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
384a0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
384b0 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
384c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
384d0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
384e0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
384f0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
38500 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
38510 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
38520 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
38530 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
38540 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
38550 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
38560 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
38570 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
38580 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
38590 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
385a0 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
385b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
385c0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
385d0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
385e0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
385f0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
38600 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
38610 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
38620 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
38630 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
38640 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
38650 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
38660 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
38670 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
38680 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
38690 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
386a0 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
386b0 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
386c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
386d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
386e0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
386f0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
38700 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
38710 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
38720 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
38730 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
38740 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
38750 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
38760 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
38770 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
38780 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
38790 28 29 5d 20 62 65