/ Hex Artifact Content
Login

Artifact 52db0e5240e6c3d355937cdc187b61999d884aff:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c  .*/.#ifndef _SQL
05e0: 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20  ITE3_H_.#define 
05f0: 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63  _SQLITE3_H_.#inc
0600: 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20  lude <stdarg.h> 
0610: 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f      /* Needed fo
0620: 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e  r the definition
0630: 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a   of va_list */..
0640: 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20  /*.** Make sure 
0650: 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73  we can call this
0660: 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e   stuff from C++.
0670: 0a 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c  .*/.#ifdef __cpl
0680: 75 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43  usplus.extern "C
0690: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
06a0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
06b0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
06c0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
06d0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
06e0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
06f0: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
0700: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
0710: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
0720: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0730: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
0740: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
0750: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
0760: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
0770: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
0780: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
0790: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
07a0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
07b0: 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  LL.#endif../*.**
07c0: 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63   These no-op mac
07d0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e 20  ros are used in 
07e0: 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66 61  front of interfa
07f0: 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73  ces to mark thos
0800: 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
0810: 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65 63  as either deprec
0820: 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d 65  ated or experime
0830: 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69  ntal.  New appli
0840: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
0850: 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65 63  d not use deprec
0860: 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73 20  ated interfaces 
0870: 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70 6f  - they are suppo
0880: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
0890: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
08a0: 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69  ity only.  Appli
08b0: 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20 73  cation writers s
08c0: 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20 74  hould be aware t
08d0: 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e  hat.** experimen
08e0: 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  tal interfaces a
08f0: 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  re subject to ch
0900: 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72 65  ange in point re
0910: 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  leases..**.** Th
0920: 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64 20  ese macros used 
0930: 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76 61  to resolve to va
0940: 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20 63  rious kinds of c
0950: 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74 68  ompiler magic th
0960: 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65  at.** would gene
0970: 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65 73  rate warning mes
0980: 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79 20  sages when they 
0990: 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74 20  were used.  But 
09a0: 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72  that.** compiler
09b0: 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70 20   magic ended up 
09c0: 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68 20  generating such 
09d0: 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67 20  a flurry of bug 
09e0: 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20  reports.** that 
09f0: 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69 74  we have taken it
0a00: 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e   all out and gon
0a10: 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20  e back to using 
0a20: 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d  simple.** noop m
0a30: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  acros..*/.#defin
0a40: 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  e SQLITE_DEPRECA
0a50: 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  TED.#define SQLI
0a60: 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a  TE_EXPERIMENTAL.
0a70: 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68  ./*.** Ensure th
0a80: 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72 65  ese symbols were
0a90: 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79 20   not defined by 
0aa0: 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68 65  some previous he
0ab0: 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69  ader file..*/.#i
0ac0: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
0ad0: 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  ION.# undef SQLI
0ae0: 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69  TE_VERSION.#endi
0af0: 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  f.#ifdef SQLITE_
0b00: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
0b10: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
0b20: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e  RSION_NUMBER.#en
0b30: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
0b40: 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
0b50: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
0b60: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20  n Numbers.**.** 
0b70: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
0b80: 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63  RSION] C preproc
0b90: 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74  essor macro in t
0ba0: 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65 61  he sqlite3.h hea
0bb0: 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73  der.** evaluates
0bc0: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74   to a string lit
0bd0: 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68 65  eral that is the
0be0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
0bf0: 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74  in the.** format
0c00: 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20 58   "X.Y.Z" where X
0c10: 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76 65   is the major ve
0c20: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c  rsion number (al
0c30: 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51  ways 3 for.** SQ
0c40: 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73 20  Lite3) and Y is 
0c50: 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f  the minor versio
0c60: 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20 69  n number and Z i
0c70: 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e 75  s the release nu
0c80: 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65  mber.)^.** ^(The
0c90: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
0ca0: 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70 72  _NUMBER] C prepr
0cb0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72 65  ocessor macro re
0cc0: 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e 74  solves to an int
0cd0: 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68 65  eger.** with the
0ce0: 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30 30   value (X*100000
0cf0: 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29 20  0 + Y*1000 + Z) 
0d00: 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64 20  where X, Y, and 
0d10: 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a 2a  Z are the same.*
0d20: 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20 69  * numbers used i
0d30: 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  n [SQLITE_VERSIO
0d40: 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c  N].)^.** The SQL
0d50: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
0d60: 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65 6e  ER for any given
0d70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
0d80: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20  te will also.** 
0d90: 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
0da0: 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d 20  he release from 
0db0: 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72 69  which it is deri
0dc0: 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20 77  ved.  Either Y w
0dd0: 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63  ill.** be held c
0de0: 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77 69  onstant and Z wi
0df0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
0e00: 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c 6c  d or else Y will
0e10: 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a   be incremented.
0e20: 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  ** and Z will be
0e30: 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a   reset to zero..
0e40: 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65 72 73  **.** Since vers
0e50: 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51 4c 69  ion 3.6.18, SQLi
0e60: 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65 20 68  te source code h
0e70: 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64 20 69  as been stored i
0e80: 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  n the.** <a href
0e90: 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66 6f 73  ="http://www.fos
0ea0: 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e 46 6f  sil-scm.org/">Fo
0eb0: 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  ssil configurati
0ec0: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a 2a 2a  on management.**
0ed0: 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20 5e 54   system</a>.  ^T
0ee0: 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  he SQLITE_SOURCE
0ef0: 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c 75 61  _ID macro evalua
0f00: 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74 72 69  tes to.** a stri
0f10: 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74 69 66  ng which identif
0f20: 69 65 73 20 61 20 70 61 72 74 69 63 75 6c 61 72  ies a particular
0f30: 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53 51 4c   check-in of SQL
0f40: 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20 69 74  ite.** within it
0f50: 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
0f60: 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73 74 65  management syste
0f70: 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  m.  ^The SQLITE_
0f80: 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73 74 72  SOURCE_ID.** str
0f90: 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ing contains the
0fa0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 6f   date and time o
0fb0: 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e 20 28  f the check-in (
0fc0: 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48 41 31  UTC) and an SHA1
0fd0: 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68 65 20  .** hash of the 
0fe0: 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20 74 72  entire source tr
0ff0: 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ee..**.** See al
1000: 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  so: [sqlite3_lib
1010: 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b  version()],.** [
1020: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1030: 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20 5b 73  on_number()], [s
1040: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1050: 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 76  )],.** [sqlite_v
1060: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1070: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1080: 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
1090: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20 20 20  QLITE_VERSION   
10a0: 20 20 20 20 20 22 2d 2d 56 45 52 53 2d 2d 22 0a       "--VERS--".
10b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
10c0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 2d 2d  ERSION_NUMBER --
10d0: 56 45 52 53 49 4f 4e 2d 4e 55 4d 42 45 52 2d 2d  VERSION-NUMBER--
10e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10f0: 53 4f 55 52 43 45 5f 49 44 20 20 20 20 20 20 22  SOURCE_ID      "
1100: 2d 2d 53 4f 55 52 43 45 2d 49 44 2d 2d 22 0a 0a  --SOURCE-ID--"..
1110: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1120: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1130: 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73   Version Numbers
1140: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
1150: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73  lite3_version, s
1160: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 0a  qlite3_sourceid.
1170: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
1180: 72 66 61 63 65 73 20 70 72 6f 76 69 64 65 20 74  rfaces provide t
1190: 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
11a0: 69 6f 6e 20 61 73 20 74 68 65 20 5b 53 51 4c 49  ion as the [SQLI
11b0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20  TE_VERSION],.** 
11c0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
11d0: 4e 55 4d 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51  NUMBER], and [SQ
11e0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
11f0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1200: 61 63 72 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65  acros.** but are
1210: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1220: 20 74 68 65 20 6c 69 62 72 61 72 79 20 69 6e 73   the library ins
1230: 74 65 61 64 20 6f 66 20 74 68 65 20 68 65 61 64  tead of the head
1240: 65 72 20 66 69 6c 65 2e 20 20 5e 28 43 61 75 74  er file.  ^(Caut
1250: 69 6f 75 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d  ious.** programm
1260: 65 72 73 20 6d 69 67 68 74 20 69 6e 63 6c 75 64  ers might includ
1270: 65 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  e assert() state
1280: 6d 65 6e 74 73 20 69 6e 20 74 68 65 69 72 20 61  ments in their a
1290: 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a  pplication to.**
12a0: 20 76 65 72 69 66 79 20 74 68 61 74 20 76 61 6c   verify that val
12b0: 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
12c0: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
12d0: 20 6d 61 74 63 68 20 74 68 65 20 6d 61 63 72 6f   match the macro
12e0: 73 20 69 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64  s in.** the head
12f0: 65 72 2c 20 61 6e 64 20 74 68 75 73 20 65 6e 73  er, and thus ens
1300: 75 72 65 20 74 68 61 74 20 74 68 65 20 61 70 70  ure that the app
1310: 6c 69 63 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63  lication is.** c
1320: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 61 74  ompiled with mat
1330: 63 68 69 6e 67 20 6c 69 62 72 61 72 79 20 61 6e  ching library an
1340: 64 20 68 65 61 64 65 72 20 66 69 6c 65 73 2e 0a  d header files..
1350: 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1360: 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72  e><pre>.** asser
1370: 74 28 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  t( sqlite3_libve
1380: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d  rsion_number()==
1390: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
13a0: 55 4d 42 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65  UMBER );.** asse
13b0: 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69 74  rt( strcmp(sqlit
13c0: 65 33 5f 73 6f 75 72 63 65 69 64 28 29 2c 53 51  e3_sourceid(),SQ
13d0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d  LITE_SOURCE_ID)=
13e0: 3d 30 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  =0 );.** assert(
13f0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1400: 6c 69 62 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c  libversion(),SQL
1410: 49 54 45 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20  ITE_VERSION)==0 
1420: 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1430: 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
1440: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
1450: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
1460: 63 6f 6e 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e  constant contain
1470: 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 5b 53  s the text of [S
1480: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a  QLITE_VERSION].*
1490: 2a 20 6d 61 63 72 6f 2e 20 20 5e 54 68 65 20 73  * macro.  ^The s
14a0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
14b0: 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  n() function ret
14c0: 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
14d0: 6f 20 74 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20  o the.** to the 
14e0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
14f0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
1500: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
1510: 6c 69 62 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20  libversion().** 
1520: 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 72 6f 76  function is prov
1530: 69 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  ided for use in 
1540: 44 4c 4c 73 20 73 69 6e 63 65 20 44 4c 4c 20 75  DLLs since DLL u
1550: 73 65 72 73 20 75 73 75 61 6c 6c 79 20 64 6f 20  sers usually do 
1560: 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 64 69 72 65  not have.** dire
1570: 63 74 20 61 63 63 65 73 73 20 74 6f 20 73 74 72  ct access to str
1580: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 77 69  ing constants wi
1590: 74 68 69 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e  thin the DLL.  ^
15a0: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c  The.** sqlite3_l
15b0: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
15c0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
15d0: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 65  rns an integer e
15e0: 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  qual to.** [SQLI
15f0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1600: 52 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  R].  ^The sqlite
1610: 33 5f 73 6f 75 72 63 65 69 64 28 29 20 66 75 6e  3_sourceid() fun
1620: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a  ction returns .*
1630: 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 20 77 68 6f 73 65 20 76 61 6c 75 65 20 69 73 20   whose value is 
1660: 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65 20  the same as the 
1670: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  .** [SQLITE_SOUR
1680: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
1690: 65 73 73 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  essor macro..**.
16a0: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
16b0: 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20  lite_version()] 
16c0: 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72  and [sqlite_sour
16d0: 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  ce_id()]..*/.SQL
16e0: 49 54 45 5f 45 58 54 45 52 4e 20 63 6f 6e 73 74  ITE_EXTERN const
16f0: 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76 65   char sqlite3_ve
1700: 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e 73 74 20 63  rsion[];.const c
1710: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
1720: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 63  version(void);.c
1730: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1740: 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64  e3_sourceid(void
1750: 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  );.int sqlite3_l
1760: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1770: 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
1780: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1790: 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70 69 6c  e Library Compil
17a0: 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20 44 69  ation Options Di
17b0: 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  agnostics.**.** 
17c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
17d0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
17e0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
17f0: 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20 69 6e  ns 0 or 1 .** in
1800: 64 69 63 61 74 69 6e 67 20 77 68 65 74 68 65 72  dicating whether
1810: 20 74 68 65 20 73 70 65 63 69 66 69 65 64 20 6f   the specified o
1820: 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69 6e 65  ption was define
1830: 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65  d at .** compile
1840: 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53 51 4c   time.  ^The SQL
1850: 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61 79 20  ITE_ prefix may 
1860: 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  be omitted from 
1870: 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e  the .** option n
1880: 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20 73 71  ame passed to sq
1890: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
18a0: 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a 2a 2a  ion_used().  .**
18b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
18c0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
18d0: 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 6c  et() function al
18e0: 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67 0a 2a  lows iterating.*
18f0: 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73 74 20  * over the list 
1900: 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  of options that 
1910: 77 65 72 65 20 64 65 66 69 6e 65 64 20 61 74 20  were defined at 
1920: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62 79 0a  compile time by.
1930: 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74 68 65  ** returning the
1940: 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20 74 69   N-th compile ti
1950: 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69 6e 67  me option string
1960: 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75 74 20  .  ^If N is out 
1970: 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c  of range,.** sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72 6e 73  on_get() returns
19a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
19b0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 0a    ^The SQLITE_ .
19c0: 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f 6d 69  ** prefix is omi
19d0: 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20 73 74  tted from any st
19e0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
19f0: 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  y .** sqlite3_co
1a00: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1a10: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72  )..**.** ^Suppor
1a20: 74 20 66 6f 72 20 74 68 65 20 64 69 61 67 6e 6f  t for the diagno
1a30: 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 20 73  stic functions s
1a40: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1a50: 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a 20 61  tion_used().** a
1a60: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nd sqlite3_compi
1a70: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 6d  leoption_get() m
1a80: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 62 79  ay be omitted by
1a90: 20 73 70 65 63 69 66 79 69 6e 67 20 74 68 65 20   specifying the 
1aa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  .** [SQLITE_OMIT
1ab0: 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44  _COMPILEOPTION_D
1ac0: 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61 74 20  IAGS] option at 
1ad0: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a  compile time..**
1ae0: 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 53 51  .** See also: SQ
1af0: 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73 71 6c  L functions [sql
1b00: 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  ite_compileoptio
1b10: 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  n_used()] and.**
1b20: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
1b30: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20 61 6e  option_get()] an
1b40: 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f  d the [compile_o
1b50: 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d 2e 0a  ptions pragma]..
1b60: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
1b70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1b80: 54 49 4f 4e 5f 44 49 41 47 53 0a 69 6e 74 20 73  TION_DIAGS.int s
1b90: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1ba0: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
1bb0: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
1bc0: 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
1bd0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1be0: 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23  on_get(int N);.#
1bf0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
1c00: 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53  I3REF: Test To S
1c10: 65 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72  ee If The Librar
1c20: 79 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a  y Is Threadsafe.
1c30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1c40: 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20  e3_threadsafe() 
1c50: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c60: 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c   zero if and onl
1c70: 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77  y if.** SQLite w
1c80: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1c90: 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f   mutexing code o
1ca0: 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68  mitted due to th
1cb0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  e.** [SQLITE_THR
1cc0: 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65  EADSAFE] compile
1cd0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69  -time option bei
1ce0: 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a  ng set to 0..**.
1cf0: 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65  ** SQLite can be
1d00: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f   compiled with o
1d10: 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65  r without mutexe
1d20: 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20  s.  When.** the 
1d30: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1d40: 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  FE] C preprocess
1d50: 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72  or macro is 1 or
1d60: 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61   2, mutexes.** a
1d70: 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53  re enabled and S
1d80: 51 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73  QLite is threads
1d90: 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a  afe.  When the.*
1da0: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1db0: 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30  SAFE] macro is 0
1dc0: 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  , .** the mutexe
1dd0: 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20  s are omitted.  
1de0: 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65  Without the mute
1df0: 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73  xes, it is not s
1e00: 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51  afe.** to use SQ
1e10: 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  Lite concurrentl
1e20: 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e  y from more than
1e30: 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a   one thread..**.
1e40: 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65  ** Enabling mute
1e50: 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61  xes incurs a mea
1e60: 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61  surable performa
1e70: 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20  nce penalty..** 
1e80: 53 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f  So if speed is o
1e90: 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61  f utmost importa
1ea0: 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65  nce, it makes se
1eb0: 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a  nse to disable.*
1ec0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20  * the mutexes.  
1ed0: 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  But for maximum 
1ee0: 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20  safety, mutexes 
1ef0: 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65  should be enable
1f00: 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  d..** ^The defau
1f10: 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66  lt behavior is f
1f20: 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65  or mutexes to be
1f30: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
1f40: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1f50: 61 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e  an be used by an
1f60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
1f70: 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74  make sure that t
1f80: 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  he.** version of
1f90: 20 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20   SQLite that it 
1fa0: 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e  is linking again
1fb0: 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  st was compiled 
1fc0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69  with.** the desi
1fd0: 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74  red setting of t
1fe0: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
1ff0: 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a  DSAFE] macro..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20  ce only reports 
2020: 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74  on the compile-t
2030: 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e  ime mutex settin
2040: 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  g.** of the [SQL
2050: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
2060: 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65  flag.  If SQLite
2070: 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
2080: 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45  h.** SQLITE_THRE
2090: 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74  ADSAFE=1 or =2 t
20a0: 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20  hen mutexes are 
20b0: 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
20c0: 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65  lt but.** can be
20d0: 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61   fully or partia
20e0: 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69  lly disabled usi
20f0: 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ng a call to [sq
2100: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a  lite3_config()].
2110: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62  ** with the verb
2120: 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  s [SQLITE_CONFIG
2130: 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20  _SINGLETHREAD], 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20  ULTITHREAD],.** 
2160: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
2170: 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e 20 20  G_SERIALIZED].  
2180: 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c  ^(The return val
2190: 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c  ue of the.** sql
21a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
21b0: 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73  ) function shows
21c0: 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c   only the compil
21d0: 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f  e-time setting o
21e0: 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65  f.** thread safe
21f0: 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d  ty, not any run-
2200: 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20  time changes to 
2210: 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64  that setting mad
2220: 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e by.** sqlite3_
2230: 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68  config(). In oth
2240: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65  er words, the re
2250: 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2260: 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61  sqlite3_threadsa
2270: 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61  fe().** is uncha
2280: 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f  nged by calls to
2290: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
22a0: 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74  ).)^.**.** See t
22b0: 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
22c0: 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  de] documentatio
22d0: 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  n for additional
22e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f   information..*/
22f0: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72  .int sqlite3_thr
2300: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
2310: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2320: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2330: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
2340: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
2350: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
2360: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2370: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
2380: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
2390: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
23a0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
23b0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
23c0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
23d0: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
23e0: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
23f0: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
2400: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
2410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
2420: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
2430: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2450: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2460: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
2470: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
2480: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
2490: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
24a0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
24b0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
24c0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
24d0: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
24e0: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
24f0: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
2500: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
2510: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2520: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2530: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
2540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
2550: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
2560: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
2570: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
2580: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
2590: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
25a0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
25b0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
25c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
25d0: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
25e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
25f0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
2600: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
2610: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
2620: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
2630: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
2640: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
2650: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
2660: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
2670: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
2680: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
2690: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
26a0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
26b0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
26c0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
26d0: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
26e0: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
26f0: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
2700: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2710: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
2720: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
2730: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
2740: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
2750: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
2760: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
2770: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
2780: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2790: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
27a0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
27b0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
27c0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
27d0: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
27e0: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
27f0: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
2800: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
2810: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
2820: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
2830: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
2840: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
2850: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
2860: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
2870: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
2880: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
2890: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
28a0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
28b0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
28c0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
28d0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
28e0: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
28f0: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2900: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2910: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2920: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2930: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2940: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2950: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2960: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2970: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2980: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2990: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
29a0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
29b0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
29c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
29d0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
29e0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
29f0: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2a00: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2a10: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2a20: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2a30: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2a40: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2a50: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2a60: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2a70: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2a80: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2a90: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2aa0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2ab0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ac0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2ad0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2ae0: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2af0: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2b00: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2b10: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2b20: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2b30: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2b40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2b50: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2b60: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2b70: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2b80: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2b90: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2ba0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2bb0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2bc0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2bd0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2be0: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2bf0: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2c00: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2c10: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2c20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c30: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2c40: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2c50: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c60: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2c70: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2c80: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2c90: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2ca0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2cb0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2cc0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2cd0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2ce0: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2cf0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2d00: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2d10: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2d20: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2d30: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2d40: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2d50: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2d60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2d70: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2d80: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2d90: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2da0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2db0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2dc0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2dd0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2de0: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2df0: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2e00: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2e10: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2e20: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2e30: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2e40: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2e50: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2e60: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2e70: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2e80: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2e90: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2ea0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2eb0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2ec0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ed0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
2ee0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2ef0: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
2f00: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f10: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
2f20: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
2f30: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
2f40: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
2f50: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
2f60: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
2f70: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
2f80: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
2f90: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2fa0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2fb0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
2fc0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
2fd0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
2fe0: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
2ff0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3000: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3010: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3020: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3030: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3040: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3050: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3060: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3070: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
3080: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
3090: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
30a0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
30b0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
30c0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
30d0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
30e0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30f0: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3100: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3110: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3120: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3130: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3140: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3150: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3160: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3170: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
3180: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
3190: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
31a0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
31b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
31c0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
31d0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
31e0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
31f0: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3200: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3210: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3220: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3230: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3240: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3250: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3260: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3270: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
3280: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
3290: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
32a0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
32b0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
32c0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
32d0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
32e0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
32f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3300: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3310: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3320: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3330: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3340: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3350: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3360: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3370: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
3380: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
3390: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
33a0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
33b0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
33c0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
33d0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
33e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
33f0: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3400: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3410: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3430: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3440: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3450: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3460: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3470: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3480: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
3490: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
34a0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
34b0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
34c0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
34d0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
34e0: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
34f0: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3500: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3510: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3520: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3530: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3540: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3550: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3560: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3570: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
3580: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
3590: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
35a0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
35b0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
35c0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
35d0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e0: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
35f0: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3600: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3610: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3620: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3630: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3640: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3650: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3660: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3670: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
3680: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
3690: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
36a0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
36b0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
36c0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
36d0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
36e0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
36f0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3700: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3710: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3720: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3730: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3740: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3750: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3760: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3770: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
3780: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
3790: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
37a0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
37b0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
37c0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
37d0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
37e0: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
37f0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3800: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3810: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3820: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3830: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3840: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3850: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3860: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3870: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
3880: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3890: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
38a0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
38b0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
38c0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
38d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
38e0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
38f0: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3900: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3910: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3920: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3930: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3940: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3950: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3960: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3970: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3980: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3990: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
39a0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
39b0: 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71  eter of.** of sq
39c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
39d0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
39e0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
39f0: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
3a00: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
3a10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3a20: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
3a30: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
3a40: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
3a50: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
3a60: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
3a70: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
3a80: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
3a90: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
3aa0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
3ab0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
3ac0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
3ad0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
3ae0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3af0: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
3b00: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
3b10: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
3b20: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
3b30: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
3b40: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
3b50: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
3b60: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
3b70: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
3b80: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b90: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3ba0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
3bb0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
3bc0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
3bd0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
3be0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
3bf0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
3c00: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
3c10: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
3c20: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
3c30: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
3c40: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
3c50: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
3c60: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
3c70: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
3c80: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
3c90: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
3ca0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
3cb0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
3cc0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
3cd0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3ce0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
3cf0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
3d00: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
3d10: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3d20: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3d30: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
3d40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
3d50: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
3d60: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
3d70: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
3d80: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
3d90: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
3da0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
3db0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
3dc0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
3dd0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
3de0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3df0: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
3e00: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
3e10: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
3e20: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
3e30: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
3e40: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
3e50: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
3e60: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
3e70: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
3e80: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
3e90: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
3ea0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
3eb0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
3ec0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
3ed0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
3ee0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3ef0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3f00: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f10: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f20: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
3f30: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
3f40: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
3f50: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
3f60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
3f70: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
3f80: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3f90: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
3fa0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
3fb0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
3fc0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
3fd0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
3fe0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
3ff0: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
4000: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
4010: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
4020: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
4030: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
4040: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
4050: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
4060: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
4070: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
4080: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
4090: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
40a0: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40d0: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
40e0: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
40f0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
4100: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4110: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
4120: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
4130: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
4140: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
4150: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
4160: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
4170: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
4180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4190: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41a0: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
41b0: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
41c0: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
41f0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
4200: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
4210: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
4220: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
4250: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
4260: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
4270: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
4280: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
4290: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
42a0: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
42b0: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
42c0: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
42d0: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
42e0: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
42f0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
4300: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4310: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4320: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
4330: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
4340: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
4350: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
4360: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
4370: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
4380: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
4390: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
43a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
43b0: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
43c0: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
43d0: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
43e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
43f0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
4400: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
4410: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
4420: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
4430: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
4440: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4450: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4460: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4470: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4480: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4490: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
44a0: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
44b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44c0: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
44d0: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
44e0: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
44f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4500: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
4510: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
4520: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
4530: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
4540: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4550: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4560: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4570: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4580: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4590: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
45a0: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
45b0: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
45c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
45d0: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
45e0: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
45f0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
4600: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
4610: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4620: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
4630: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
4640: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4650: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4660: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4670: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4680: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4690: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
46a0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
46b0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
46c0: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
46d0: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
46e0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
4710: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
4720: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
4730: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
4740: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4750: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4760: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4770: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4780: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4790: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
47a0: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
47b0: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
47c0: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
47d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
47e0: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
47f0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
4800: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
4810: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
4820: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
4830: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
4840: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4850: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4860: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4870: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4880: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
48a0: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
48b0: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
48c0: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
48d0: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
48e0: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
48f0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
4900: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
4910: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4920: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
4930: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
4940: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4960: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4970: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4980: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4990: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
49b0: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
49c0: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
49d0: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
49e0: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
49f0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
4a00: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
4a10: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
4a30: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
4a40: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4a50: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4a60: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4a70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4a80: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4a90: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4aa0: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4ab0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
4ad0: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
4ae0: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
4af0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
4b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4b10: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
4b20: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
4b30: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
4b40: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
4b50: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
4b60: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
4b70: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
4b80: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
4b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4ba0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
4bb0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
4bc0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
4bd0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
4be0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
4bf0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
4c00: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
4c10: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
4c40: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4c50: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
4c60: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
4c70: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
4c80: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
4c90: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
4ca0: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
4cb0: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
4cc0: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
4cd0: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
4ce0: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
4cf0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
4d00: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
4d10: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
4d20: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
4d30: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
4d40: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
4d50: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
4d60: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
4d70: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
4d80: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
4d90: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
4da0: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
4db0: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
4dc0: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
4dd0: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
4de0: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
4df0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
4e00: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
4e10: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
4e20: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
4e30: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
4e40: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
4e50: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
4e60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
4e70: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
4e80: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
4e90: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
4ea0: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
4eb0: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
4ec0: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
4ed0: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
4ee0: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
4ef0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
4f00: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
4f10: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
4f20: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
4f30: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
4f40: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
4f50: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
4f60: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
4f70: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
4f80: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
4f90: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
4fa0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
4fb0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
4fc0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
4fd0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
4fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
4ff0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
5000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5010: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5020: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
5030: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
5040: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
5050: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5060: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
5070: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
5080: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
5090: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50a0: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
50b0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
50d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50e0: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
50f0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5100: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
5110: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5120: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
5130: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5140: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
5150: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5160: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
5170: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5180: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
5190: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51a0: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
51b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
51c0: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
51d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
51e0: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
51f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5200: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
5210: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5220: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
5230: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5240: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
5250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5260: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
5270: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
5280: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
5290: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52a0: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
52b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
52c0: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
52d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
52e0: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
52f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5300: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
5310: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5320: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
5330: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5340: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
5350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5360: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
5370: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5380: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
5390: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53a0: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
53b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
53c0: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
53d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
53e0: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
53f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5400: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
5410: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5420: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
5430: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5440: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
5450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5460: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
5470: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5480: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
5490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54a0: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
54b0: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
54c0: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
54d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
54e0: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
54f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5500: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
5510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5520: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
5530: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5540: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
5550: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5560: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
5570: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5580: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
5590: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55a0: 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20  _IOERR_VNODE    
55b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
55c0: 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29  _IOERR | (27<<8)
55d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
55e0: 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20  _IOERR_AUTH     
55f0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5600: 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29  _IOERR | (28<<8)
5610: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5620: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
5630: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5640: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5650: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5660: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5670: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5680: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5690: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56a0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
56b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56c0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
56d0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56e0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56f0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
5700: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5710: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5720: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
5730: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5740: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5750: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5760: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5770: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5780: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5790: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
57a0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
57b0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
57c0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
57d0: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57f0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
5800: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
5810: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
5820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5830: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5840: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5850: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5860: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5870: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5880: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5890: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
58a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
58b0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
58c0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
58d0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58f0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
5900: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
5910: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
5920: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5930: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5940: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5950: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5960: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5970: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5980: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5990: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
59a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
59b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
59c0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
59d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59e0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5a00: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
5a10: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
5a20: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
5a30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a40: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a50: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a60: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a70: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a80: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a90: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5aa0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5ab0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5ac0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ad0: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5ae0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5af0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5b10: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5b20: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5b30: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b50: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b60: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b70: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b80: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b90: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5ba0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5bb0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5bc0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5bd0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5be0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bf0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5c00: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5c10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c20: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5c30: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5c60: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c70: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c80: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5ca0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5cb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5cc0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ce0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5d00: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5d20: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5d30: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d40: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d50: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d60: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d70: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d80: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d90: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5da0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5db0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5dc0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5dd0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5de0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5df0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5e00: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5e10: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5e20: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e30: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e50: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e60: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e70: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e80: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5ea0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5eb0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5ec0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ed0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5ef0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5f00: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5f10: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5f30: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f40: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
5f50: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5f60: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f70: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f80: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
5f90: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5fa0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
5fb0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5fc0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5fd0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fe0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ff0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
6000: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
6010: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
6020: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6030: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6070: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6080: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6090: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
60a0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
60b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
60c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
60d0: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60e0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
60f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6100: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
6130: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6140: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6150: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6160: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
6170: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6180: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6190: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
61a0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
61b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
61c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
61d0: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61e0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
61f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6200: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
6210: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
6220: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
6230: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6240: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6250: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6260: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6270: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6280: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6290: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
62b0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
62c0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
62d0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62e0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
6300: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
6310: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
6320: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6330: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6340: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6360: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6370: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6380: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 49 4c 45 50  QLITE_OPEN_FILEP
6390: 52 4f 54 45 43 54 49 4f 4e 5f 4d 41 53 4b 20 20  ROTECTION_MASK  
63a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
63c0: 78 30 30 37 30 30 30 30 30 0a 0a 2f 2a 20 52 65  x00700000../* Re
63d0: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
63e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63f0: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
6400: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6410: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
6420: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
6430: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
6440: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
6450: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6460: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
6470: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
6480: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
6490: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
64a0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
64b0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
64c0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
64d0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
64e0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
64f0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
6500: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
6510: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
6520: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
6530: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
6540: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
6550: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
6560: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
6570: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
6580: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6590: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
65a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
65b0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
65c0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
65d0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
65e0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
65f0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
6600: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
6610: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
6620: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
6630: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
6640: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
6650: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
6660: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
6670: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
6680: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
6690: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
66a0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
66b0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
66c0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
66d0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
66e0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
66f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
6700: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
6710: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6720: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
6730: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
6740: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
6750: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
6760: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
6770: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
6780: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
6790: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
67a0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
67b0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
67c0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
67d0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
67e0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
67f0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
6800: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
6810: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
6820: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
6830: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
6840: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
6850: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
6860: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
6870: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
6880: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20  o be unchanged. 
6890: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
68a0: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
68b0: 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20  EN_OPEN.** flag 
68c0: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 61 20  indicate that a 
68d0: 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64  file cannot be d
68e0: 65 6c 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e  eleted when open
68f0: 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45  .  The.** SQLITE
6900: 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
6910: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20   flag indicates 
6920: 74 68 61 74 20 74 68 65 20 66 69 6c 65 20 69 73  that the file is
6930: 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79   on.** read-only
6940: 20 6d 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f   media and canno
6950: 74 20 62 65 20 63 68 61 6e 67 65 64 20 65 76 65  t be changed eve
6960: 6e 20 62 79 20 70 72 6f 63 65 73 73 65 73 20 77  n by processes w
6970: 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20  ith.** elevated 
6980: 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23  privileges..*/.#
6990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
69a0: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
69b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
69c0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
69d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
69e0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
69f0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
6a00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a10: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
6a20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6a30: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
6a40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
6a50: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6a60: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
6a70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a80: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
6a90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
6aa0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6ab0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
6ac0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6ad0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
6ae0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6af0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
6b00: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
6b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6b20: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
6b30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6b40: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
6b50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6b60: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
6b70: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
6b80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b90: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
6ba0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6bb0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
6bc0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
6bd0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
6be0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
6bf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6c00: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6c10: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6c20: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6c30: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6c40: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6c50: 78 30 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e  x00001000.#defin
6c60: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49  e SQLITE_IOCAP_I
6c70: 4d 4d 55 54 41 42 4c 45 20 20 20 20 20 20 20 20  MMUTABLE        
6c80: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
6c90: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6ca0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
6cb0: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
6cc0: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
6cd0: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
6ce0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
6cf0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
6d00: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
6d10: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
6d20: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
6d30: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
6d40: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6d50: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
6d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d70: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
6d80: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6d90: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
6da0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
6db0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
6dc0: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
6dd0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
6de0: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
6df0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6e00: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
6e10: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
6e20: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
6e30: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
6e40: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
6e50: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
6e60: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
6e70: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e80: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6e90: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
6ea0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
6eb0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ec0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
6ed0: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
6ee0: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
6ef0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
6f00: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
6f10: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
6f20: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
6f30: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
6f40: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
6f50: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
6f60: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
6f70: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
6f80: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
6f90: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
6fa0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
6fb0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
6fc0: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
6fd0: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
6fe0: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
6ff0: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
7000: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
7010: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7020: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
7030: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
7040: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
7050: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
7060: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
7070: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
7080: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7090: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
70a0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
70b0: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
70c0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
70d0: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
70e0: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
70f0: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
7100: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
7110: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
7120: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
7130: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
7140: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
7150: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
7160: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
7170: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
7180: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7190: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
71a0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
71b0: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
71c0: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
71d0: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
71e0: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
71f0: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
7200: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
7210: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
7220: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
7230: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
7240: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
7250: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7260: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
7270: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
7280: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
7290: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
72a0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
72b0: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
72c0: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
72d0: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
72e0: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
72f0: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
7300: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
7310: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
7320: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
7330: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
7340: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
7350: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
7360: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
7370: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
7380: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
7390: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
73a0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
73b0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
73c0: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
73d0: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
73e0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
73f0: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
7400: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
7410: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
7420: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
7430: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
7440: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
7450: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
7460: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
7470: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
7480: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
7490: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
74a0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
74b0: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
74c0: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
74d0: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
74e0: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
74f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
7500: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
7510: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
7520: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
7530: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
7540: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
7550: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
7560: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
7570: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
7580: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7590: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
75a0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
75b0: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
75c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
75d0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
75e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
75f0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
7600: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
7610: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
7620: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
7630: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
7640: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7650: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
7660: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7670: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
7680: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
7690: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
76a0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
76b0: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
76c0: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
76d0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
76e0: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
76f0: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
7700: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
7710: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
7720: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
7730: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
7740: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
7750: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
7760: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7770: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
7780: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7790: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
77a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
77b0: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
77c0: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
77d0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
77e0: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
77f0: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
7800: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
7810: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
7820: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
7830: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
7840: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
7850: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
7860: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
7870: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
7880: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
7890: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
78a0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
78b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
78c0: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
78d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
78e0: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
78f0: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
7900: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
7910: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
7920: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
7930: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
7940: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
7950: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
7960: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
7970: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
7980: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
7990: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
79a0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
79b0: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
79c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
79d0: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
79e0: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
79f0: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
7a00: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
7a10: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
7a20: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
7a30: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
7a40: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
7a50: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
7a60: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
7a70: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
7a80: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7a90: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
7aa0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7ab0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
7ac0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7ad0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
7ae0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
7af0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
7b00: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7b10: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
7b20: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
7b30: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
7b40: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
7b50: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
7b60: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
7b70: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
7b80: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
7b90: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
7ba0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7bb0: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
7bc0: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
7bd0: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
7be0: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
7bf0: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
7c00: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
7c10: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
7c20: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
7c30: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
7c40: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
7c50: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
7c60: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
7c70: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
7c80: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
7c90: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
7ca0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
7cb0: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
7cc0: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
7cd0: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
7ce0: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
7cf0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
7d00: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
7d10: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
7d20: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
7d30: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
7d40: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
7d50: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
7d60: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
7d70: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
7d80: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
7d90: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
7da0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
7db0: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
7dc0: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
7dd0: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
7de0: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
7df0: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
7e00: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
7e10: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
7e20: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
7e30: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
7e40: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
7e50: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
7e60: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
7e70: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
7e80: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7e90: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7ea0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7eb0: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7ec0: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7ed0: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7ee0: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7ef0: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7f00: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7f10: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65   use..** A [file
7f20: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
7f30: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
7f40: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
7f50: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
7f60: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7f70: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7f80: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7f90: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7fa0: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7fb0: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7fc0: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7fd0: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
7fe0: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7ff0: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
8000: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
8010: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
8020: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
8030: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
8040: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
8050: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
8060: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
8070: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
8080: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
8090: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
80a0: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
80b0: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
80c0: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
80d0: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
80e0: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
80f0: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
8100: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
8110: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
8120: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
8130: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
8140: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
8150: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
8160: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
8170: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
8180: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
8190: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
81a0: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
81b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
81c0: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
81d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
81e0: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
81f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8200: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
8210: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8220: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
8230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8240: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
8250: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8260: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
8270: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8280: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
8290: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
82a0: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
82b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
82c0: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
82d0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
82e0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
82f0: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
8300: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
8310: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
8320: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
8330: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
8340: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
8350: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8360: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
8370: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
8380: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
8390: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
83a0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
83b0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
83c0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
83d0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
83e0: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
83f0: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
8400: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
8410: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
8420: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
8430: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
8440: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
8450: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
8460: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
8470: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
8480: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
8490: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
84a0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
84b0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
84c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
84d0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
84e0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
84f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
8500: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
8510: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
8520: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
8530: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
8540: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
8550: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
8560: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
8570: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
8580: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
8590: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
85a0: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
85b0: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
85c0: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
85d0: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
85e0: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
85f0: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
8600: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
8610: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8620: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
8630: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
8640: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
8650: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8660: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8670: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
8680: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
8690: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
86a0: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
86b0: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
86c0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
86d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
86e0: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
86f0: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
8700: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8710: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8720: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
8730: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
8740: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
8750: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
8760: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
8770: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
8780: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
8790: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
87a0: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
87b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
87c0: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
87d0: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
87e0: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
87f0: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
8800: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
8810: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8820: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
8830: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
8840: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
8850: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
8860: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
8870: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
8880: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
8890: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
88a0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
88b0: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
88c0: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
88d0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
88e0: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
88f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8900: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
8910: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
8920: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
8930: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
8940: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
8950: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
8960: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
8970: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
8980: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
8990: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
89a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
89b0: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
89c0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
89d0: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
89e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
89f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
8a00: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
8a10: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
8a20: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
8a30: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8a40: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
8a50: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63  */.  int (*xFetc
8a60: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
8a70: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8a80: 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c  iOfst, int iAmt,
8a90: 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69   void **pp);.  i
8aa0: 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73  nt (*xUnfetch)(s
8ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8ac0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8ad0: 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f  t, void *p);.  /
8ae0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8af0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8b00: 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20  rsion 3 */.  /* 
8b10: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8b20: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8b30: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8b40: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8b50: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8b60: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8b70: 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  Opcodes.** KEYWO
8b80: 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72  RDS: {file contr
8b90: 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c  ol opcodes} {fil
8ba0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8bb0: 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  }.**.** These in
8bc0: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
8bd0: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
8be0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8bf0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
8c00: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8c10: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
8c20: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
8c30: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
8c40: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
8c50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
8c60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
8c70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a  L_LOCKSTATE]].**
8c80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8c90: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8ca0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8cb0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8cc0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8cd0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8ce0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8cf0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8d00: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8d10: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8d20: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8d30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8d40: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8d50: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8d60: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8d70: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8d80: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8d90: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8da0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8db0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8dc0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8dd0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8de0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8df0: 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20  ing and is only 
8e00: 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74  available when t
8e10: 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a  he SQLITE_TEST.*
8e20: 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  * compile-time o
8e30: 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
8e40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8e50: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
8e60: 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  T]].** The [SQLI
8e70: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
8e80: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
8e90: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
8ea0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
8eb0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
8ec0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
8ed0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
8ee0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
8ef0: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
8f00: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
8f10: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
8f20: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8f30: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
8f40: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
8f50: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
8f60: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
8f70: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
8f80: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
8f90: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
8fa0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
8fb0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
8fc0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
8fd0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
8fe0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
8ff0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9000: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d  NTL_CHUNK_SIZE]]
9010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
9020: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
9030: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
9040: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
9050: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
9060: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
9070: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
9080: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
9090: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
90a0: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
90b0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
90c0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
90d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
90e0: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
90f0: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
9100: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
9110: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
9120: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
9130: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
9140: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
9150: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
9160: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
9170: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
9180: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
9190: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
91a0: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
91b0: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
91c0: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
91d0: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
91e0: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ystems..**.** <l
91f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9200: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a  _FILE_POINTER]].
9210: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
9220: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
9230: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
9240: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
9250: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
9260: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
9270: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
9280: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
9290: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
92a0: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
92b0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
92c0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
92d0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
92e0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
92f0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
9300: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9310: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
9320: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
9330: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
9340: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9350: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
9360: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
9370: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
9380: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
9390: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
93a0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
93b0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
93c0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
93d0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
93e0: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
93f0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
9400: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
9410: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
9420: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
9430: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
9440: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
9450: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
9460: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
9470: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
9480: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
9490: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
94a0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
94b0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
94c0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
94d0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
94e0: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
94f0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
9500: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
9510: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
9520: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
9530: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
9540: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
9550: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
9560: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
9570: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
9580: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
9590: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
95a0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
95b0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
95c0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
95d0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
95e0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
95f0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
9600: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
9610: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
9620: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
9630: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
9640: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
9650: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
9660: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
9670: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
9680: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
9690: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
96a0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
96b0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
96c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
96d0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
96e0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
96f0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
9700: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
9710: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
9720: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
9730: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
9740: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
9750: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
9760: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
9770: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
9780: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
9790: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
97a0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
97b0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
97c0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
97d0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
97e0: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
97f0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
9800: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
9810: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
9820: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
9830: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
9840: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
9850: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
9860: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
9870: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
9880: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9890: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
98a0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
98b0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
98c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
98d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
98e0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
98f0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9900: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
9910: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
9920: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
9930: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
9940: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
9950: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
9960: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9970: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9980: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9990: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
99a0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
99b0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
99c0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
99d0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
99e0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
99f0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9a00: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
9a10: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
9a20: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
9a30: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
9a40: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
9a50: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
9a60: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9a70: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9a80: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9a90: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9aa0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9ab0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9ac0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9ad0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9ae0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
9af0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9b00: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
9b10: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
9b20: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
9b30: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
9b40: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
9b50: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
9b60: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9b70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9b80: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9b90: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9ba0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9bb0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9bc0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9bd0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
9be0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
9bf0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9c00: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
9c10: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
9c20: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
9c30: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
9c40: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
9c50: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
9c60: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9c70: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9c80: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9c90: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9ca0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9cb0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9cc0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9cd0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
9ce0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9cf0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9d00: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
9d10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
9d20: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
9d30: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9d40: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
9d50: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
9d60: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9d70: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9d80: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9d90: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9da0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9db0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9dc0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9dd0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
9de0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
9df0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9e00: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
9e10: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
9e20: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
9e30: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
9e40: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9e50: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
9e60: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9e70: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9e80: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9e90: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9ea0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9eb0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9ec0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9ed0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
9ee0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
9ef0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9f00: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9f10: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9f20: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9f30: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9f40: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9f50: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9f60: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9f70: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9f80: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9f90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9fa0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9fb0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9fc0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9fd0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9fe0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9ff0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
a000: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
a010: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
a020: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a030: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
a040: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
a050: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a060: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a070: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a080: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
a090: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
a0a0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
a0b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
a0c0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
a0d0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
a0e0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
a0f0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
a100: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
a110: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
a120: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
a130: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
a140: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
a150: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
a160: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
a170: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
a180: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a190: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
a1a0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
a1b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a1c0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
a1d0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
a1e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
a1f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a200: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
a210: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
a220: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
a230: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
a240: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
a250: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
a260: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
a270: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
a280: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
a290: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
a2a0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
a2b0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
a2c0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
a2d0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
a2e0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
a2f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a300: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
a310: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
a320: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a330: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
a340: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
a350: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
a360: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
a370: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
a380: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
a390: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
a3a0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
a3b0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
a3c0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
a3d0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
a3e0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
a3f0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
a400: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
a410: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
a420: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a430: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
a440: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a450: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
a460: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a470: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a480: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a490: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a4a0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a4b0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a4c0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a4d0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a4e0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
a4f0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
a500: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
a510: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
a520: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
a530: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
a540: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
a550: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
a560: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a570: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
a580: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
a590: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
a5a0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
a5b0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
a5c0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
a5d0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
a5e0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
a5f0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
a600: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
a610: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
a620: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
a630: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
a640: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
a650: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
a660: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
a670: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
a680: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
a690: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
a6a0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
a6b0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
a6c0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
a6d0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
a6e0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
a6f0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a700: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
a710: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a720: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
a730: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
a740: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
a750: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
a760: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
a770: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
a780: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
a790: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
a7a0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
a7b0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
a7c0: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
a7d0: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
a7e0: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
a7f0: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
a800: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
a810: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
a820: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
a830: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
a840: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
a850: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
a860: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
a870: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
a880: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
a890: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a8a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
a8b0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
a8c0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
a8d0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
a8e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a8f0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
a900: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
a910: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
a920: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
a930: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
a940: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
a950: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
a960: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
a970: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
a980: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
a990: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
a9a0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a9b0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
a9c0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
a9d0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
a9e0: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
a9f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
aa00: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
aa10: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
aa20: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
aa30: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
aa40: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
aa50: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
aa60: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
aa70: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
aa80: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
aa90: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
aaa0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
aab0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
aac0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
aad0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
aae0: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
aaf0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
ab00: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
ab10: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
ab20: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
ab30: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
ab40: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
ab50: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
ab60: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
ab70: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
ab80: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
ab90: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
aba0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
abb0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
abc0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
abd0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
abe0: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
abf0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
ac00: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
ac10: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
ac20: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
ac30: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ac40: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
ac50: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ac60: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
ac70: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
ac80: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
ac90: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
aca0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
acb0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
acc0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
acd0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
ace0: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
acf0: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
ad00: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
ad10: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
ad20: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
ad30: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
ad40: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
ad50: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
ad60: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
ad70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
ad80: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
ad90: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
ada0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
adb0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
adc0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
add0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
ade0: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
adf0: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
ae00: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
ae10: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
ae20: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
ae30: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
ae40: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
ae50: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
ae60: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
ae70: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
ae80: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
ae90: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
aea0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
aeb0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
aec0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
aed0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
aee0: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
aef0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
af00: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
af10: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
af20: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
af30: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
af40: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
af50: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
af60: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
af70: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
af80: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
af90: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
afa0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
afb0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
afc0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
afd0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
afe0: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
aff0: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
b000: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
b010: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
b020: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
b030: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
b040: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
b050: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
b060: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
b070: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
b080: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
b090: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
b0a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
b0b0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
b0c0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
b0d0: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
b0e0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
b0f0: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
b100: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
b110: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
b120: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
b130: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
b140: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
b150: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
b160: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
b170: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
b180: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
b190: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
b1a0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
b1b0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1c0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
b1d0: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
b1e0: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
b1f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
b200: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
b210: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
b220: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
b230: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
b240: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
b250: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
b260: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
b270: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
b280: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
b290: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
b2a0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
b2b0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
b2c0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
b2d0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
b2e0: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
b2f0: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
b300: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
b310: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
b320: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
b330: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
b340: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
b350: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
b360: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
b370: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
b380: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
b390: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
b3a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b3b0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
b3c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3d0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
b3e0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
b3f0: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
b400: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
b410: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
b420: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
b430: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
b440: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
b450: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
b460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
b470: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
b480: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
b490: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
b4a0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b4b0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
b4c0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
b4d0: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
b4e0: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
b4f0: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
b500: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
b510: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
b520: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
b530: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
b540: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
b550: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
b560: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
b570: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
b580: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
b590: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
b5a0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
b5b0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
b5c0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
b5d0: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
b5e0: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
b5f0: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
b600: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b610: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
b620: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
b630: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
b640: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
b650: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
b660: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
b670: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
b680: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
b690: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
b6a0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
b6b0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
b6c0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
b6d0: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
b6e0: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
b6f0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b700: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
b710: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
b720: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
b730: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
b740: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
b750: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
b760: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
b770: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
b780: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
b790: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
b7a0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
b7b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b7c0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
b7d0: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
b7e0: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b7f0: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
b800: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
b810: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
b820: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b830: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
b840: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
b850: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
b860: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
b870: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
b880: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
b890: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
b8a0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
b8b0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
b8c0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
b8d0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b8e0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
b8f0: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
b900: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b910: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
b920: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
b930: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
b940: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
b950: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
b960: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
b970: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
b980: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
b990: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
b9a0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
b9b0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
b9c0: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
b9d0: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
b9e0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
b9f0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
ba00: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
ba10: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
ba20: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ba30: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
ba40: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
ba50: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
ba60: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
ba70: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
ba80: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
ba90: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
baa0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
bab0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
bac0: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
bad0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
bae0: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
baf0: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
bb00: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
bb10: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
bb20: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
bb30: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
bb40: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
bb50: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
bb60: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
bb70: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
bb80: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
bb90: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
bba0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bbb0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
bbc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
bbd0: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
bbe0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
bbf0: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
bc00: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
bc10: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
bc20: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
bc30: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
bc40: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bc50: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
bc60: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bc70: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
bc80: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
bc90: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
bca0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
bcb0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
bcc0: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
bcd0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
bce0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
bcf0: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
bd00: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
bd10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
bd20: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
bd30: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
bd40: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
bd50: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
bd60: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
bd70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bd80: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
bd90: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
bda0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bdb0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
bdc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
bdd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bde0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
bdf0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
be00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
be10: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
be20: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
be30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
be40: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
be50: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
be60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
be70: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
be80: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
be90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bea0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
beb0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
bec0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
bed0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
bee0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
bef0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
bf00: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
bf10: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
bf20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
bf30: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
bf40: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
bf50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
bf60: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
bf70: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
bf80: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
bf90: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
bfa0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
bfb0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
bfc0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
bfd0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
bfe0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
bff0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
c000: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
c010: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
c020: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
c030: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
c040: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
c050: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
c060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c070: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
c080: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
c090: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c0a0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
c0b0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
c0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c0d0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
c0e0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
c0f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c100: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
c110: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
c120: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c130: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
c140: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
c150: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c160: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
c170: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
c180: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c190: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
c1a0: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e         26.#defin
c1b0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
c1c0: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  FS_POINTER      
c1d0: 20 20 20 20 20 20 32 37 0a 0a 2f 2a 20 64 65 70        27../* dep
c1e0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
c1f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c200: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
c210: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c220: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
c230: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c240: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
c250: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
c260: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
c270: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
c280: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
c290: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
c2a0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
c2b0: 53 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a  ST_ERRNO.../*.**
c2c0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
c2d0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
c2e0: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
c2f0: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
c300: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
c310: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
c320: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
c330: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
c340: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
c350: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
c360: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
c370: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
c380: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
c390: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
c3a0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
c3b0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
c3c0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c3d0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
c3e0: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
c3f0: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
c400: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
c410: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
c420: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
c430: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
c440: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
c450: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
c460: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
c470: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
c480: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
c490: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
c4a0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
c4b0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
c4c0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
c4d0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
c4e0: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
c4f0: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
c500: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
c510: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
c520: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
c530: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
c540: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
c550: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
c560: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
c570: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
c580: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
c590: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
c5a0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
c5b0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
c5c0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
c5d0: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
c5e0: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
c5f0: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
c600: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
c610: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
c620: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
c630: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
c640: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
c650: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
c660: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
c670: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
c680: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
c690: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
c6a0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
c6b0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
c6c0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
c6d0: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
c6e0: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
c6f0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
c700: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
c710: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
c720: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
c730: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
c740: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
c750: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
c760: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
c770: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
c780: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
c790: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
c7a0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
c7b0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
c7c0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
c7d0: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c7e0: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
c7f0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
c800: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
c810: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
c820: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
c830: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
c840: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
c850: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
c860: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
c870: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
c880: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
c890: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
c8a0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
c8b0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
c8c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
c8d0: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
c8e0: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
c8f0: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
c900: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
c910: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
c920: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
c930: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
c940: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
c950: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
c960: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
c970: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
c980: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
c990: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
c9a0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
c9b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
c9c0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
c9d0: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
c9e0: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
c9f0: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
ca00: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
ca10: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
ca20: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
ca30: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
ca40: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
ca50: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
ca60: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
ca70: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
ca80: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
ca90: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
caa0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
cab0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
cac0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
cad0: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
cae0: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
caf0: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
cb00: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
cb10: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
cb20: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
cb30: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
cb40: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
cb50: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
cb60: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
cb70: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
cb80: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
cb90: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
cba0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
cbb0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
cbc0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
cbd0: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
cbe0: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
cbf0: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
cc00: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
cc10: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
cc20: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
cc30: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
cc40: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
cc50: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
cc60: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
cc70: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
cc80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
cc90: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
cca0: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
ccb0: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
ccc0: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
ccd0: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
cce0: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
ccf0: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
cd00: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
cd10: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
cd20: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
cd30: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
cd40: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
cd50: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
cd60: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
cd70: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
cd80: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
cd90: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
cda0: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
cdb0: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
cdc0: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
cdd0: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
cde0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cdf0: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
ce00: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
ce10: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
ce20: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
ce30: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
ce40: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
ce50: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
ce60: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
ce70: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
ce80: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
ce90: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
cea0: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
ceb0: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
cec0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
ced0: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
cee0: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
cef0: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
cf00: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
cf10: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
cf20: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
cf30: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
cf40: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
cf50: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
cf60: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
cf70: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
cf80: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
cf90: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
cfa0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
cfb0: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
cfc0: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
cfd0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
cfe0: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
cff0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
d000: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
d010: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
d020: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
d030: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
d040: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
d050: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
d060: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d070: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
d080: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
d090: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
d0a0: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
d0b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
d0c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
d0d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
d0e0: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
d0f0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d100: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
d110: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
d120: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
d130: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
d140: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
d150: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
d160: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
d170: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
d180: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
d190: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
d1a0: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
d1b0: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
d1c0: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
d1d0: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
d1e0: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
d1f0: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
d200: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
d210: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
d220: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
d230: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
d240: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
d250: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
d260: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
d270: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
d280: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
d290: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
d2a0: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
d2b0: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
d2c0: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
d2d0: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
d2e0: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
d2f0: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
d300: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
d310: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
d320: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
d330: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
d340: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
d350: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
d360: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
d370: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
d380: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
d390: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
d3a0: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
d3b0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
d3c0: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
d3d0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
d3e0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
d3f0: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
d400: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
d410: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
d420: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
d430: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
d440: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
d450: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
d460: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
d470: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
d480: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
d490: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
d4a0: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
d4b0: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
d4c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
d4d0: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
d4e0: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
d4f0: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
d500: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
d510: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
d520: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
d530: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
d540: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
d550: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
d560: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
d570: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
d580: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
d590: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
d5a0: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
d5b0: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
d5c0: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
d5d0: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
d5e0: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
d5f0: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
d600: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
d610: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
d620: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
d630: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
d640: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
d650: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
d660: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
d670: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
d680: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
d690: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
d6a0: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
d6b0: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
d6c0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
d6d0: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
d6e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
d6f0: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
d700: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
d710: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
d720: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
d730: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
d740: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
d750: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
d760: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
d770: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
d780: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
d790: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
d7a0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
d7b0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
d7c0: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
d7d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
d7e0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
d7f0: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
d800: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
d810: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
d820: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
d830: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
d840: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
d850: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
d860: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
d870: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
d880: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
d890: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
d8a0: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
d8b0: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
d8c0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d8d0: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
d8e0: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
d8f0: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
d900: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
d910: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
d920: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
d930: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
d940: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
d950: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d960: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
d970: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
d980: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
d990: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
d9a0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
d9b0: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
d9c0: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
d9d0: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
d9e0: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
d9f0: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
da00: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
da10: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
da20: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
da30: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
da40: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
da50: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
da60: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
da70: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
da80: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
da90: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
daa0: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
dab0: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
dac0: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
dad0: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
dae0: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
daf0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
db00: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
db10: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
db20: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
db30: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
db40: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
db50: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
db60: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
db70: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
db80: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
db90: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
dba0: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
dbb0: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
dbc0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
dbd0: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
dbe0: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
dbf0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
dc00: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
dc10: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
dc20: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
dc30: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
dc40: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
dc50: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
dc60: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
dc70: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
dc80: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
dc90: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
dca0: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
dcb0: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
dcc0: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
dcd0: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
dce0: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
dcf0: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
dd00: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
dd10: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
dd20: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
dd30: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
dd40: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
dd50: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
dd60: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
dd70: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
dd80: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
dd90: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
dda0: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
ddb0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ddc0: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
ddd0: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
dde0: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
ddf0: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
de00: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
de10: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
de20: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
de30: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
de40: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
de50: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
de60: 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
de70: 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
de80: 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
de90: 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
dea0: 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
deb0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
dec0: 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
ded0: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
dee0: 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
def0: 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
df00: 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
df10: 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
df20: 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
df30: 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
df40: 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
df50: 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
df60: 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
df70: 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
df80: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
df90: 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
dfa0: 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
dfb0: 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
dfc0: 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
dfd0: 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
dfe0: 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
dff0: 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
e000: 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
e010: 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
e020: 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
e030: 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
e040: 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
e050: 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
e060: 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
e070: 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
e080: 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
e090: 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
e0a0: 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
e0b0: 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
e0c0: 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
e0d0: 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
e0e0: 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
e0f0: 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
e100: 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
e110: 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
e120: 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
e130: 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
e140: 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
e150: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
e160: 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
e170: 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
e180: 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
e190: 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
e1a0: 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
e1b0: 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
e1c0: 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
e1d0: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
e1e0: 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
e1f0: 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
e200: 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
e210: 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
e220: 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
e230: 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
e240: 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
e250: 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
e260: 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
e270: 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
e280: 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
e290: 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
e2a0: 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
e2b0: 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
e2c0: 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
e2d0: 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
e2e0: 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
e2f0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
e300: 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
e310: 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
e320: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
e330: 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
e340: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
e350: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
e360: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
e370: 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
e380: 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
e390: 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
e3a0: 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
e3b0: 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
e3c0: 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
e3d0: 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
e3e0: 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
e3f0: 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
e400: 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
e410: 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
e420: 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
e430: 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
e440: 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
e450: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
e460: 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
e470: 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
e480: 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
e490: 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
e4a0: 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
e4b0: 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
e4c0: 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
e4d0: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
e4e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e4f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e500: 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
e510: 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
e520: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
e530: 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
e540: 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
e550: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e560: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e570: 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
e580: 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
e590: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
e5a0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
e5b0: 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
e5c0: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
e5d0: 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
e5e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e5f0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
e600: 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
e610: 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
e620: 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
e630: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e640: 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
e650: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
e660: 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
e670: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
e680: 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
e690: 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
e6a0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
e6b0: 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
e6c0: 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
e6d0: 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
e6e0: 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
e6f0: 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
e700: 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
e710: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
e720: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
e730: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
e740: 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
e750: 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
e760: 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
e770: 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
e780: 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
e790: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
e7a0: 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
e7b0: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
e7c0: 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
e7d0: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e7e0: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e7f0: 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
e800: 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
e810: 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
e820: 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
e830: 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
e840: 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
e850: 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
e860: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
e870: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
e880: 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
e890: 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
e8a0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
e8b0: 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
e8c0: 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
e8d0: 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
e8e0: 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
e8f0: 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
e900: 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
e910: 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
e920: 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
e930: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
e940: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
e950: 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
e960: 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
e970: 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
e980: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e990: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e9a0: 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
e9b0: 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
e9c0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
e9d0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
e9e0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
e9f0: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ea00: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ea10: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
ea20: 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
ea30: 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
ea40: 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
ea50: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
ea60: 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
ea70: 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
ea80: 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
ea90: 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
eaa0: 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
eab0: 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
eac0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
ead0: 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
eae0: 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
eaf0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
eb00: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
eb10: 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
eb20: 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
eb30: 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
eb40: 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
eb60: 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
eb70: 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
eb80: 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
eb90: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
eba0: 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
ebb0: 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
ebc0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
ebd0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
ebe0: 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
ebf0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
ec00: 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
ec10: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
ec20: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
ec30: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
ec40: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
ec50: 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
ec60: 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
ec70: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
ec80: 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
ec90: 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
eca0: 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
ecb0: 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
ecc0: 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
ecd0: 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
ece0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
ecf0: 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
ed00: 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
ed10: 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
ed20: 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
ed30: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
ed40: 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
ed50: 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
ed60: 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
ed70: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
ed80: 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
ed90: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
eda0: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
edb0: 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
edc0: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
edd0: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
ede0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
edf0: 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
ee00: 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
ee10: 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
ee20: 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
ee30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
ee40: 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
ee50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ee60: 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
ee70: 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
ee80: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
ee90: 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
eea0: 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
eeb0: 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
eec0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eed0: 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
eee0: 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
eef0: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
ef00: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ef10: 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
ef20: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
ef30: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
ef40: 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
ef50: 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
ef60: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
ef70: 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
ef80: 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
ef90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
efa0: 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
efb0: 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
efc0: 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
efd0: 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
efe0: 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
eff0: 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
f000: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
f010: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
f020: 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
f030: 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
f040: 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
f050: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
f060: 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
f070: 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
f080: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
f090: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
f0a0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
f0b0: 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
f0c0: 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
f0d0: 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
f0e0: 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
f0f0: 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
f100: 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
f110: 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
f120: 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72  iven on the corr
f130: 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
f140: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
f150: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
f160: 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
f170: 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
f180: 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
f190: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f1a0: 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
f1b0: 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
f1c0: 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
f1d0: 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
f1e0: 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
f1f0: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
f200: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
f210: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
f220: 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
f230: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
f240: 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
f250: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f260: 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
f270: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f280: 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
f290: 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
f2a0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
f2b0: 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
f2c0: 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
f2d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
f2e0: 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
f2f0: 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
f300: 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
f310: 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
f320: 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
f330: 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
f340: 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
f350: 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
f360: 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
f370: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f380: 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
f390: 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
f3a0: 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
f3b0: 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
f3c0: 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
f3d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f3e0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
f3f0: 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
f400: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
f410: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
f420: 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
f430: 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
f440: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
f450: 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
f460: 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
f470: 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
f480: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
f490: 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
f4a0: 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
f4b0: 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
f4c0: 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
f4d0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
f4e0: 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
f4f0: 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
f500: 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
f510: 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
f520: 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
f530: 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
f540: 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
f550: 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
f560: 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
f570: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
f580: 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
f590: 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
f5a0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f5b0: 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
f5c0: 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
f5d0: 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
f5e0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
f5f0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
f600: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f610: 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
f620: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
f630: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
f640: 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
f650: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
f660: 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
f670: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
f680: 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
f690: 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
f6a0: 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
f6b0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
f6c0: 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
f6d0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f6e0: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
f6f0: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
f700: 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
f710: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
f720: 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
f730: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
f740: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
f750: 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
f760: 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
f770: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f780: 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
f790: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
f7a0: 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
f7b0: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
f7c0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
f7d0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
f7e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
f7f0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f800: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
f810: 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
f820: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
f830: 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
f840: 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
f850: 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
f860: 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
f870: 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
f880: 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
f890: 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
f8a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
f8b0: 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
f8c0: 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
f8d0: 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
f8e0: 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
f8f0: 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
f900: 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
f910: 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
f920: 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
f930: 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
f940: 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
f950: 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
f960: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
f970: 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
f980: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
f990: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
f9a0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
f9b0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
f9c0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
f9d0: 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
f9e0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
f9f0: 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
fa00: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
fa10: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
fa20: 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
fa30: 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
fa40: 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
fa50: 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
fa60: 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
fa70: 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
fa80: 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
fa90: 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
faa0: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
fab0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
fac0: 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
fad0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fae0: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
faf0: 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
fb00: 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
fb10: 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
fb20: 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
fb30: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
fb40: 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
fb50: 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
fb60: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fb70: 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
fb80: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
fb90: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
fba0: 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
fbb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
fbc0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
fbd0: 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
fbe0: 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
fbf0: 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
fc00: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
fc10: 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
fc20: 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
fc30: 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
fc40: 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
fc50: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fc60: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
fc70: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
fc80: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
fc90: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
fca0: 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
fcb0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
fcc0: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
fcd0: 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
fce0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
fcf0: 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
fd00: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
fd10: 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
fd20: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
fd30: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fd40: 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
fd50: 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
fd60: 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
fd70: 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
fd80: 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
fd90: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
fda0: 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
fdb0: 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
fdc0: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
fdd0: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
fde0: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
fdf0: 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
fe00: 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
fe10: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
fe20: 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
fe30: 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
fe40: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
fe50: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
fe60: 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
fe70: 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
fe80: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
fe90: 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
fea0: 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
feb0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
fec0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
fed0: 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
fee0: 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
fef0: 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
ff00: 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
ff10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
ff20: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
ff30: 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
ff40: 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
ff50: 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
ff60: 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
ff70: 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
ff80: 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
ff90: 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
ffa0: 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
ffb0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
ffc0: 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
ffd0: 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
ffe0: 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
fff0: 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
10000 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
10010 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
10020 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
10030 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
10040 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
10050 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
10060 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
10070 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
10080 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
10090 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
100a0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
100b0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
100c0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
100d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
100e0 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
100f0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
10100 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
10110 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
10120 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
10130 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
10140 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
10150 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
10160 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10170 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
10180 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
10190 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
101a0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
101b0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
101c0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
101d0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
101e0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
101f0 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
10200 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
10210 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
10220 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
10230 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
10240 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
10250 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
10260 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
10270 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
10280 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
10290 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
102a0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
102b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
102c0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
102d0 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
102e0 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
102f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
10300 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
10310 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
10320 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
10330 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
10340 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
10350 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
10360 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
10370 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
10380 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
10390 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
103a0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
103b0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74   failure..*/.int
103c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
103d0 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73  ize(void);.int s
103e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
103f0 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
10400 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
10410 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
10420 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
10430 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10440 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
10450 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
10460 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10470 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10480 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
10490 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
104a0 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
104b0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
104c0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
104d0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
104e0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
104f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
10500 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
10510 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
10520 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
10530 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
10540 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
10550 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
10560 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
10570 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
10580 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
10590 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
105a0 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
105b0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
105c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
105d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
105e0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
105f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
10600 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
10610 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
10620 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
10630 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
10640 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
10650 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
10660 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
10670 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
10680 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
10690 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
106a0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
106b0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
106c0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
106d0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
106e0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
106f0 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
10700 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
10710 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
10720 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
10730 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
10740 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
10750 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
10760 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
10770 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
10780 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
10790 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
107a0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
107b0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
107c0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
107d0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
107e0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
107f0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
10800 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
10810 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
10820 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
10830 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10840 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
10850 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
10860 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
10870 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
10880 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
10890 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
108a0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
108b0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
108c0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
108d0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
108e0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
108f0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10900 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
10910 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
10920 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
10930 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10940 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
10950 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
10960 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
10970 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
10980 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
10990 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
109a0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
109b0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
109c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
109d0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
109e0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73   code]..*/.int s
109f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e  qlite3_config(in
10a00 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t, ...);../*.** 
10a10 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
10a20 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ure database con
10a30 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48  nections.** METH
10a40 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
10a50 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
10a60 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10a70 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
10a80 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
10a90 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10aa0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
10ab0 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
10ac0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
10ad0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
10ae0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
10af0 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
10b00 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
10b10 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
10b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
10b30 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
10b40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
10b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
10b60 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
10b70 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10b80 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
10b90 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
10ba0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10bb0 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
10bc0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
10bd0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
10be0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
10bf0 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
10c00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10c10 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
10c20 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
10c30 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10c40 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10c50 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
10c60 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
10c70 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
10c80 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
10c90 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
10ca0 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
10cb0 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
10cc0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
10cd0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
10ce0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
10cf0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
10d00 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
10d10 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
10d20 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
10d30 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
10d40 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10d50 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
10d60 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
10d70 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
10d80 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
10d90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10da0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
10db0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
10dc0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
10dd0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
10de0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
10df0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
10e00 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
10e10 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
10e20 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
10e30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
10e40 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
10e50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
10e60 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
10e70 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
10e80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
10e90 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
10ea0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
10eb0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10ec0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
10ed0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
10ee0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
10ef0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
10f00 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
10f10 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
10f20 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
10f30 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10f40 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10f50 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
10f60 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
10f70 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
10f80 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
10f90 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
10fa0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
10fb0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
10fc0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
10fd0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
10fe0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
10ff0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
11000 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
11010 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
11020 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
11030 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
11040 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
11050 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
11060 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
11070 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
11080 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
11090 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
110a0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
110b0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
110c0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
110d0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
110e0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
110f0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
11100 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
11110 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
11120 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
11130 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
11140 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
11150 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
11160 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
11170 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
11180 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
11190 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
111a0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
111b0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
111c0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
111d0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
111e0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
111f0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
11200 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
11210 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
11220 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
11230 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
11240 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
11250 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
11260 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
11270 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11280 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
11290 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
112a0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
112b0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
112c0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
112d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
112e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
112f0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
11300 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
11310 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
11320 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
11330 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
11340 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
11350 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
11360 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
11370 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
11380 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
11390 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
113a0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
113b0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
113c0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
113d0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
113e0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
113f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11400 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
11410 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
11420 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
11430 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
11440 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
11450 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
11460 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
11470 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
11480 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
11490 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
114a0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
114b0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
114c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
114d0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
114e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
114f0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
11500 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
11510 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
11520 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
11530 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
11540 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
11550 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
11560 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
11570 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
11580 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
11590 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
115a0 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
115b0 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
115c0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
115d0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
115e0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
115f0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
11600 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
11610 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11620 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11630 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11640 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11650 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11660 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11670 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11680 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11690 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
116a0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
116b0 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
116c0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
116d0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
116e0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
116f0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
11700 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
11710 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11720 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11730 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11740 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11750 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11760 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11770 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11780 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11790 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
117a0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
117b0 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
117c0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
117d0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
117e0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
117f0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11800 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
11810 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11820 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11830 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11840 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11850 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11860 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11870 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11880 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11890 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
118a0 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
118b0 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
118c0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
118d0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
118e0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
118f0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
11900 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
11910 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11920 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11930 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11940 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11950 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11960 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11970 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11980 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11990 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
119a0 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
119b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
119c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
119d0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
119e0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
119f0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11a00 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
11a10 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11a20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11a30 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11a40 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
11a50 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
11a60 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
11a70 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
11a80 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
11a90 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
11aa0 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
11ab0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
11ac0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
11ad0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
11ae0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
11af0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
11b00 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
11b10 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
11b20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
11b30 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
11b40 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
11b50 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
11b60 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
11b70 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
11b80 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11b90 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11ba0 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
11bb0 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
11bc0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
11bd0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
11be0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
11bf0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
11c00 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
11c10 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
11c20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
11c30 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
11c40 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
11c50 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
11c60 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
11c70 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
11c80 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
11c90 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
11ca0 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
11cb0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11cc0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
11cd0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
11ce0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11cf0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
11d00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
11d10 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11d20 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11d30 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11d40 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
11d50 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
11d60 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
11d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11d80 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
11d90 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
11da0 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11db0 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
11dc0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
11dd0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
11de0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
11df0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
11e00 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
11e10 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11e20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
11e30 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
11e40 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11e50 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
11e60 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
11e70 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
11e80 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
11e90 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
11ea0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11eb0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
11ec0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11ed0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11ee0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11ef0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
11f00 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
11f10 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11f20 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11f30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11f40 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
11f50 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11f60 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
11f70 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
11f80 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
11f90 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
11fa0 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
11fb0 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
11fc0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
11fd0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11fe0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11ff0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
12000 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
12010 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12020 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12030 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12040 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
12050 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
12060 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
12070 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
12080 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
12090 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
120a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
120b0 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
120c0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
120d0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
120e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
120f0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
12100 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
12110 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
12120 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12130 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
12140 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
12150 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
12160 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
12170 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
12180 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
12190 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
121a0 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
121b0 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
121c0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
121d0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
121e0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
121f0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
12200 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
12210 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
12220 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
12230 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
12240 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
12250 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
12260 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
12270 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12280 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12290 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
122a0 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
122b0 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
122c0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
122d0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
122e0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
122f0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
12300 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
12310 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
12320 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
12330 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
12340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12350 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
12360 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
12370 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12380 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12390 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
123a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
123b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
123c0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
123d0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
123e0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
123f0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
12400 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
12410 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
12420 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
12430 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12440 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
12450 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
12460 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
12470 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12480 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
12490 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
124a0 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
124b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
124c0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
124d0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
124e0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
124f0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
12500 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
12510 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
12520 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
12530 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
12540 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
12550 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
12560 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
12570 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
12580 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
12590 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
125a0 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
125b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
125c0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
125d0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
125e0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
125f0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
12600 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
12610 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12620 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12630 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12640 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12650 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12670 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12680 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12690 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
126a0 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
126b0 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
126c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
126d0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
126e0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
126f0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
12700 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
12710 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12720 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12730 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12740 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12750 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12760 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12770 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12780 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12790 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
127a0 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
127b0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
127c0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
127d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
127e0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
127f0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
12800 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
12810 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12820 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12830 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12840 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12850 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12860 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12870 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
12890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
128a0 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65  LLOC option take
128b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
128c0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
128d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
128e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
128f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12900 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
12910 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
12920 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12930 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12940 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12950 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12960 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12970 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12980 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12990 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
129a0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
129b0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
129c0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
129d0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
129e0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
129f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12a00 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12a10 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12a20 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12a30 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12a50 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12a60 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12a70 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12a80 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
12a90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12aa0 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12ab0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12ac0 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69  ument which.** i
12ad0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
12ae0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
12af0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
12b00 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
12b10 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  e..** The [sqlit
12b20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
12b30 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
12b40 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
12b50 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
12b60 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
12b70 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
12b80 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
12b90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12ba0 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12bb0 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
12bc0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
12bd0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
12be0 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
12bf0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
12c00 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
12c10 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
12c20 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
12c30 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
12c40 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12c50 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
12c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12c70 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
12c80 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
12c90 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
12ca0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12cb0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
12cc0 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e   type int,.** in
12cd0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
12ce0 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e  oolean, which en
12cf0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
12d00 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e  s the collection
12d10 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c   of.** memory al
12d20 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12d30 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f  ics. ^(When memo
12d40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
12d50 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20  atistics are.** 
12d60 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f  disabled, the fo
12d70 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
12d80 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
12d90 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
12da0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
12db0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
12dc0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
12dd0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
12de0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
12df0 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
12e00 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
12e10 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
12e20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
12e30 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20  status64()].**  
12e40 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d   </ul>)^.** ^Mem
12e50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
12e60 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e  tatistics are en
12e70 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12e80 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69   unless SQLite i
12e90 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
12ea0 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55  th [SQLITE_DEFAU
12eb0 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20  LT_MEMSTATUS]=0 
12ec0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65  in which case me
12ed0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
12ee0 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
12ef0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
12f00 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  fault..** </dd>.
12f10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12f20 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20  ONFIG_SCRATCH]] 
12f30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12f40 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a  G_SCRATCH</dt>.*
12f50 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49  * <dd> ^The SQLI
12f60 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
12f70 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  H option specifi
12f80 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
12f90 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  ry buffer.** tha
12fa0 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
12fb0 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d   for scratch mem
12fc0 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72  ory.  ^(There ar
12fd0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
12fe0 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43  s.** to SQLITE_C
12ff0 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20  ONFIG_SCRATCH:  
13000 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
13010 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
13020 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
13030 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
13040 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
13050 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
13060 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
13070 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
13080 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
13090 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
130a0 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
130b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
130c0 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .)^.** The first
130d0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
130e0 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
130f0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
13100 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
13110 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
13120 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
13130 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74  ^SQLite will not
13140 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f   use more than o
13150 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65  ne scratch buffe
13160 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a  rs per thread..*
13170 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13180 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73  ever request a s
13190 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68  cratch buffer th
131a0 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20  at is more than 
131b0 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64  6.** times the d
131c0 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a  atabase page siz
131d0 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65  e..** ^If SQLite
131e0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
131f0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
13200 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
13210 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
13220 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
13230 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
13240 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
13250 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
13260 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
13270 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
13280 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65  eded.<p>.** ^Whe
13290 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  n the applicatio
132a0 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61  n provides any a
132b0 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68  mount of scratch
132c0 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a   memory using.**
132d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
132e0 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61  CRATCH, SQLite a
132f0 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72  voids unnecessar
13300 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69  y large.** [sqli
13310 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20  te3_malloc|heap 
13320 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a  allocations]..**
13330 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b   This can help [
13340 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65  Robson proof|pre
13350 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  vent memory allo
13360 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d  cation failures]
13370 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20   due to heap.** 
13380 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  fragmentation in
13390 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65   low-memory embe
133a0 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a  dded systems..**
133b0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
133c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
133d0 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c  ECACHE]] <dt>SQL
133e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
133f0 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
13400 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
13410 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f  NFIG_PAGECACHE o
13420 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
13430 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a  a memory pool.**
13440 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e   that SQLite can
13450 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74   use for the dat
13460 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
13470 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
13480 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  t page.** cache 
13490 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20  implementation. 
134a0 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67   .** This config
134b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
134c0 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20  s a no-op if an 
134d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
134e0 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  ne page.** cache
134f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13500 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20  is loaded using 
13510 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  the [SQLITE_CONF
13520 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20  IG_PCACHE2]..** 
13530 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65  ^There are three
13540 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51   arguments to SQ
13550 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
13560 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72  CACHE: A pointer
13570 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c   to.** 8-byte al
13580 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d  igned memory (pM
13590 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  em), the size of
135a0 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65   each page cache
135b0 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61   line (sz),.** a
135c0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
135d0 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29   cache lines (N)
135e0 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
135f0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
13600 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
13610 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
13620 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
13630 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
13640 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70  512 and 65536) p
13650 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62  lus some extra b
13660 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ytes for each.**
13670 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e   page header.  ^
13680 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  The number of ex
13690 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64  tra bytes needed
136a0 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61   by the page hea
136b0 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65  der.** can be de
136c0 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b  termined using [
136d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
136e0 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20  ACHE_HDRSZ]..** 
136f0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
13700 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
13710 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
13720 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72  * for the sz par
13730 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72  ameter to be lar
13740 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61  ger than necessa
13750 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a  ry.  The pMem.**
13760 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
13770 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  e either a NULL 
13780 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69  pointer or a poi
13790 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74  nter to an 8-byt
137a0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f  e.** aligned blo
137b0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20  ck of memory of 
137c0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
137d0 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a  tes, otherwise.*
137e0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  * subsequent beh
137f0 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
13800 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65  ed..** ^When pMe
13810 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53  m is not NULL, S
13820 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76  QLite will striv
13830 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d  e to use the mem
13840 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20  ory provided.** 
13850 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20  to satisfy page 
13860 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c  cache needs, fal
13870 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71  ling back to [sq
13880 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
13890 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63  if.** a page cac
138a0 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65  he line is large
138b0 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20  r than sz bytes 
138c0 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65  or if all of the
138d0 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20   pMem buffer.** 
138e0 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a  is exhausted..**
138f0 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c   ^If pMem is NUL
13900 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a  L and N is non-z
13910 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64  ero, then each d
13920 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13930 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e  on.** does an in
13940 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63  itial bulk alloc
13950 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63  ation for page c
13960 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66  ache memory.** f
13970 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
13980 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e  loc()] sufficien
13990 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69  t for N cache li
139a0 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69  nes if N is posi
139b0 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31  tive or.** of -1
139c0 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e  024*N bytes if N
139d0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20   is negative, . 
139e0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
139f0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
13a00 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
13a10 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
13a20 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69  vided by the ini
13a30 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  tial.** allocati
13a40 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  on, then SQLite 
13a50 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
13a60 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72  _malloc()] separ
13a70 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a  ately for each.*
13a80 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63  * additional cac
13a90 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a  he line. </dd>.*
13aa0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13ab0 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
13ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
13ad0 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
13ae0 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13af0 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73  IG_HEAP option s
13b00 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
13b10 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
13b20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20  .** that SQLite 
13b30 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c  will use for all
13b40 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
13b50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13b60 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e  n needs.** beyon
13b70 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
13b80 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
13b90 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
13ba0 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  and.** [SQLITE_C
13bb0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
13bc0 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45  ..** ^The SQLITE
13bd0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74  _CONFIG_HEAP opt
13be0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
13bf0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
13c00 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77  is compiled.** w
13c10 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49  ith either [SQLI
13c20 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
13c30 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e  3] or [SQLITE_EN
13c40 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e  ABLE_MEMSYS5] an
13c50 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51  d returns.** [SQ
13c60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69  LITE_ERROR] if i
13c70 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65  nvoked otherwise
13c80 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20  ..** ^There are 
13c90 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20  three arguments 
13ca0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
13cb0 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62  _HEAP:.** An 8-b
13cc0 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
13cd0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
13ce0 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
13cf0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
13d00 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
13d10 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
13d20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
13d30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
13d40 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
13d50 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
13d60 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
13d70 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
13d80 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
13d90 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
13da0 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
13db0 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
13dc0 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
13dd0 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
13de0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
13df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13e00 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
13e10 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
13e20 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
13e30 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76  n the alternativ
13e40 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
13e50 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64  cator is engaged
13e60 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f   to handle all o
13e70 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79  f SQLites memory
13e80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
13e90 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
13ea0 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
13eb0 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73  ory pointer) mus
13ec0 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  t be aligned to 
13ed0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75  an 8-byte.** bou
13ee0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
13ef0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
13f00 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75  SQLite will be u
13f10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
13f20 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
13f30 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70  ion size is capp
13f40 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61  ed at 2**12. Rea
13f50 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a  sonable values.*
13f60 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75  * for the minimu
13f70 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
13f80 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75  e are 2**5 throu
13f90 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a  gh 2**8.</dd>.**
13fa0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13fb0 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  FIG_MUTEX]] <dt>
13fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13fd0 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TEX</dt>.** <dd>
13fe0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
13ff0 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f  NFIG_MUTEX optio
14000 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14010 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14020 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  is a.** pointer 
14030 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
14040 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14050 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14060 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
14070 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
14080 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  es alternative l
14090 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
140a0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
140b0 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74  ed.** in place t
140c0 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
140d0 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
140e0 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
140f0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a  makes a copy of.
14100 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
14110 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
14120 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
14130 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
14140 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
14150 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14160 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
14170 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
14180 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
14190 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
141a0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
141b0 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
141c0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
141d0 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
141e0 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
141f0 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
14200 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
14210 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
14220 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
14230 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
14240 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
14250 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14260 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
14270 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
14280 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
14290 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
142a0 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
142b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
142c0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
142d0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
142e0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
142f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14300 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14310 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
14320 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14330 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
14340 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
14350 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
14360 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
14370 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  utex_methods].**
14380 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
14390 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
143a0 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
143b0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29  mutex routines.)
143c0 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
143d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
143e0 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
143f0 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63  ault mutex alloc
14400 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14410 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14420 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d   used to track m
14430 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70  utex usage for p
14440 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72  erformance.** pr
14450 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69  ofiling or testi
14460 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ng, for example.
14470 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
14480 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
14490 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
144a0 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
144b0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
144c0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
144d0 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
144e0 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
144f0 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
14500 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
14510 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
14520 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
14530 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
14540 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
14550 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e  FIG_GETMUTEX con
14560 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14570 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
14580 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
14590 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
145a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
145b0 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  ASIDE]] <dt>SQLI
145c0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
145d0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
145e0 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
145f0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f  NFIG_LOOKASIDE o
14600 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20  ption takes two 
14610 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64  arguments that d
14620 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20  etermine.** the 
14630 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20  default size of 
14640 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
14650 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61   on each [databa
14660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
14670 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
14680 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
14690 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
146a0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
146b0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
146c0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
146d0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
146e0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
146f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14700 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43  n.)^  ^(SQLITE_C
14710 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a  ONFIG_LOOKASIDE.
14720 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64  ** sets the <i>d
14730 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
14740 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
14750 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14760 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70  LOOKASIDE].** op
14770 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33  tion to [sqlite3
14780 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  _db_config()] ca
14790 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61  n be used to cha
147a0 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
147b0 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
147c0 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c  on on individual
147d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20   connections.)^ 
147e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
147f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14800 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
14810 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c  _CONFIG_PCACHE2<
14820 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14830 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14840 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  _PCACHE2 option 
14850 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14860 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
14870 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74   .** a pointer t
14880 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
14890 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
148a0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
148b0 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ect specifies.**
148c0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74   the interface t
148d0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
148e0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
148f0 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69  tion.)^.** ^SQLi
14900 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
14910 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
14920 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14930 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a   object.</dd>.**
14940 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
14950 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
14960 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14970 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
14980 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
14990 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
149a0 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  ETPCACHE2 option
149b0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
149c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a  argument which.*
149d0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
149e0 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  o an [sqlite3_pc
149f0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
14a00 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
14a10 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20  opies of.** the 
14a20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63  current page cac
14a30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
14a40 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
14a50 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
14a60 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14a70 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
14a80 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
14a90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53  t>.** <dd> The S
14aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14ab0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
14ac0 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65  to configure the
14ad0 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61   SQLite.** globa
14ae0 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a  l [error log]..*
14af0 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  * (^The SQLITE_C
14b00 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
14b10 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
14b20 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
14b30 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
14b40 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
14b50 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
14b60 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
14b70 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
14b80 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
14b90 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
14ba0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
14bb0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
14bc0 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
14bd0 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
14be0 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
14bf0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
14c00 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
14c10 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
14c20 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
14c30 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
14c40 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
14c50 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
14c60 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
14c70 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14c80 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
14c90 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
14ca0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
14cb0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14cc0 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
14cd0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
14ce0 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
14cf0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
14d00 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
14d10 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
14d20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
14d30 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
14d40 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
14d50 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
14d60 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
14d70 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
14d80 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14d90 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
14da0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
14db0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
14dc0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
14dd0 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
14de0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14df0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
14e00 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
14e10 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
14e20 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
14e30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
14e40 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
14e50 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
14e60 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
14e70 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
14e80 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
14e90 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
14ea0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
14eb0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
14ec0 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
14ed0 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
14ee0 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
14ef0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
14f00 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
14f10 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
14f20 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
14f30 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
14f40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
14f50 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
14f60 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
14f70 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  >^(The SQLITE_CO
14f80 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20  NFIG_URI option 
14f90 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
14fa0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
14fb0 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a  int..** If non-z
14fc0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
14fd0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14fe0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
14ff0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
15000 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52  zero,.** then UR
15010 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
15020 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
15030 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
15040 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15050 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ** enabled, all 
15060 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64  filenames passed
15070 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
15080 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
15090 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  pen_v2()],.** [s
150a0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
150b0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
150c0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
150d0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
150e0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
150f0 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
15100 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
15110 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
15120 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
15130 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
15140 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
15150 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
15160 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c  ed. ^If it is gl
15170 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c  obally disabled,
15180 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a   filenames are.*
15190 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74  * only interpret
151a0 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68  ed as URIs if th
151b0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
151c0 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  I flag is set wh
151d0 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  en the.** databa
151e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
151f0 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65   opened. ^(By de
15200 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c  fault, URI handl
15210 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a  ing is globally.
15220 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65  ** disabled. The
15230 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d   default value m
15240 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79  ay be changed by
15250 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20   compiling with 
15260 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  the.** [SQLITE_U
15270 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64  SE_URI] symbol d
15280 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  efined.)^.**.** 
15290 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
152a0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
152b0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
152c0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
152d0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
152e0 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
152f0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
15300 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e  NDEX_SCAN option
15310 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15320 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d  integer.** argum
15330 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
15340 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
15350 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74  olean in order t
15360 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
15370 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  ble.** the use o
15380 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
15390 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
153a0 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71  e scans in the q
153b0 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a  uery optimizer..
153c0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
153d0 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72  setting is deter
153e0 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  mined.** by the 
153f0 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f  [SQLITE_ALLOW_CO
15400 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
15410 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  N] compile-time 
15420 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f  option, or is "o
15430 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f  n".** if that co
15440 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
15450 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a  n is omitted..**
15460 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   The ability to 
15470 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20  disable the use 
15480 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
15490 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
154a0 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62  le scans.** is b
154b0 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f  ecause some inco
154c0 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65  rrectly coded le
154d0 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  gacy application
154e0 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74  s might malfunct
154f0 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20  ion.** when the 
15500 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20  optimization is 
15510 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64  enabled.  Provid
15520 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20  ing the ability 
15530 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68  to.** disable th
15540 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61  e optimization a
15550 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c  llows the older,
15560 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69   buggy applicati
15570 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  on code to work.
15580 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  ** without chang
15590 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65  e even with newe
155a0 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
155b0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  Lite..**.** [[SQ
155c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
155d0 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  HE]] [[SQLITE_CO
155e0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d  NFIG_GETPCACHE]]
155f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15600 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64  ONFIG_PCACHE and
15610 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
15620 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e  ETPCACHE.** <dd>
15630 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61   These options a
15640 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20  re obsolete and 
15650 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73  should not be us
15660 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a  ed by new code..
15670 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61  ** They are reta
15680 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  ined for backwar
15690 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
156a0 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d   but are now no-
156b0 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ops..** </dd>.**
156c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
156d0 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20  FIG_SQLLOG]].** 
156e0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
156f0 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e  G_SQLLOG.** <dd>
15700 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f  This option is o
15710 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
15720 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69   sqlite is compi
15730 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15740 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
15750 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65  QLLOG] pre-proce
15760 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e  ssor macro defin
15770 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72  ed. The first ar
15780 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a  gument should.**
15790 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
157a0 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
157b0 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  ype void(*)(void
157c0 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74  *,sqlite3*,const
157d0 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a   char*, int)..**
157e0 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75   The second shou
157f0 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76  ld be of type (v
15800 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62  oid*). The callb
15810 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ack is invoked b
15820 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a  y the library.**
15830 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61   in three separa
15840 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  te circumstances
15850 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  , identified by 
15860 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
15870 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   as the.** fourt
15880 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20  h parameter. If 
15890 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
158a0 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20  eter is 0, then 
158b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
158c0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65  nection.** passe
158d0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
158e0 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73  argument has jus
158f0 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54  t been opened. T
15900 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
15910 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61  t.** points to a
15920 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69   buffer containi
15930 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ng the name of t
15940 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65  he main database
15950 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a   file. If the.**
15960 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
15970 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65  r is 1, then the
15980 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
15990 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61  hat the third pa
159a0 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74  rameter.** point
159b0 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65  s to has just be
159c0 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c  en executed. Or,
159d0 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   if the fourth p
159e0 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74  arameter is 2, t
159f0 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65  hen.** the conne
15a00 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73  ction being pass
15a10 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
15a20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65   parameter is be
15a30 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a  ing closed. The.
15a40 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  ** third paramet
15a50 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c  er is passed NUL
15a60 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20  L In this case. 
15a70 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75   An example of u
15a80 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e  sing this.** con
15a90 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15aa0 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e  n can be seen in
15ab0 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f   the "test_sqllo
15ac0 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65  g.c" source file
15ad0 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e   in.** the canon
15ae0 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72  ical SQLite sour
15af0 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a  ce tree.</dd>.**
15b00 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15b10 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  FIG_MMAP_SIZE]].
15b20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
15b30 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a  NFIG_MMAP_SIZE.*
15b40 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f  * <dd>^SQLITE_CO
15b50 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74  NFIG_MMAP_SIZE t
15b60 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20  akes two 64-bit 
15b70 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33  integer (sqlite3
15b80 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a  _int64) values.*
15b90 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64  * that are the d
15ba0 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65  efault mmap size
15bb0 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61   limit (the defa
15bc0 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a  ult setting for.
15bd0 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f  ** [PRAGMA mmap_
15be0 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d  size]) and the m
15bf0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
15c00 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a  map size limit..
15c10 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
15c20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f  setting can be o
15c30 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63  verridden by eac
15c40 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
15c50 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65  ction using.** e
15c60 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d  ither the [PRAGM
15c70 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d  A mmap_size] com
15c80 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e  mand, or by usin
15c90 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  g the.** [SQLITE
15ca0 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
15cb0 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20  ] file control. 
15cc0 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61   ^(The maximum a
15cd0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
15ce0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65  .** will be sile
15cf0 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69  ntly truncated i
15d00 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74  f necessary so t
15d10 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  hat it does not 
15d20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f  exceed the.** co
15d30 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
15d40 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
15d50 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
15d60 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
15d70 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15d80 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
15d90 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
15da0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
15db0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
15dc0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
15dd0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
15de0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
15df0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
15e00 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15e10 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
15e20 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15e30 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15e40 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  SIZE.** <dd>^The
15e50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
15e60 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70  IN32_HEAPSIZE op
15e70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
15e80 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
15e90 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
15ea0 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68  for Windows with
15eb0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e   the [SQLITE_WIN
15ec0 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70  32_MALLOC] pre-p
15ed0 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a  rocessor macro.*
15ee0 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49  * defined. ^SQLI
15ef0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15f00 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
15f10 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
15f20 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
15f30 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
15f40 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
15f50 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
15f60 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   heap..**.** [[S
15f70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15f80 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c  CHE_HDRSZ]].** <
15f90 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15fa0 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a  _PCACHE_HDRSZ.**
15fb0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
15fc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48  _CONFIG_PCACHE_H
15fd0 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65  DRSZ option take
15fe0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
15ff0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  eter which.** is
16000 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16010 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69   integer and wri
16020 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e  tes into that in
16030 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72  teger the number
16040 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74   of extra.** byt
16050 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75  es per page requ
16060 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61  ired for each pa
16070 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f  ge in [SQLITE_CO
16080 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16090 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f  .** The amount o
160a0 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65  f extra space re
160b0 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67  quired can chang
160c0 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  e depending on t
160d0 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20  he compiler,.** 
160e0 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c  target platform,
160f0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
16100 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ion..**.** [[SQL
16110 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a  ITE_CONFIG_PMASZ
16120 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
16130 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a  _CONFIG_PMASZ.**
16140 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
16150 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70  _CONFIG_PMASZ op
16160 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
16170 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
16180 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73  ich.** is an uns
16190 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
161a0 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69  d sets the "Mini
161b0 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f  mum PMA Size" fo
161c0 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61  r the multithrea
161d0 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f  ded.** sorter to
161e0 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20   that integer.  
161f0 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69  The default mini
16200 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20  mum PMA Size is 
16210 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53  set by the.** [S
16220 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41  QLITE_SORTER_PMA
16230 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  SZ] compile-time
16240 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68   option.  New th
16250 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68  reads are launch
16260 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69  ed.** to help wi
16270 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f  th sort operatio
16280 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72  ns when multithr
16290 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a  eaded sorting.**
162a0 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69   is enabled (usi
162b0 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74  ng the [PRAGMA t
162c0 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29  hreads] command)
162d0 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20   and the amount 
162e0 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f  of content.** to
162f0 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65   be sorted excee
16300 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65  ds the page size
16310 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d   times the minim
16320 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52  um of the.** [PR
16330 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d  AGMA cache_size]
16340 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69   setting and thi
16350 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c  s value..** </dl
16360 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
16370 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
16380 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
16390 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
163a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
163b0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
163c0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
163d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
163e0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
163f0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
16400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
16410 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
16420 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
16430 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
16440 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16450 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
16460 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
16470 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16480 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16490 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
164a0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
164b0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
164c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
164d0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
164e0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
164f0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
16500 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16510 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
16520 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
16530 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
16540 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
16550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
16560 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
16570 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
16580 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16590 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
165a0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
165b0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
165c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
165d0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
165e0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
165f0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
16600 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
16610 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
16620 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
16630 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
16640 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
16650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16660 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
16670 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
16680 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16690 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
166a0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
166b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
166c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
166d0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
166e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
166f0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
16700 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
16710 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
16720 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16730 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
16740 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
16750 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16760 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
16770 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
16780 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
16790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
167a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
167b0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
167c0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
167d0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
167e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
167f0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
16800 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
16810 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16820 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
16830 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
16840 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  og, void* */.#de
16850 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16860 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20  IG_MMAP_SIZE    
16870 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69  22  /* sqlite3_i
16880 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e  nt64, sqlite3_in
16890 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t64 */.#define S
168a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
168b0 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20  32_HEAPSIZE     
168c0 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   23  /* int nByt
168d0 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
168e0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
168f0 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20 20 32  E_HDRSZ        2
16900 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a  4  /* int *psz *
16910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16920 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20  _CONFIG_PMASZ   
16930 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
16940 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20  /* unsigned int 
16950 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  szPma */../*.** 
16960 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
16970 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
16980 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
16990 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
169a0 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
169b0 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
169c0 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
169d0 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
169e0 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
169f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
16a00 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
16a10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
16a20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
16a30 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
16a40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
16a50 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
16a60 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
16a70 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
16a80 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
16a90 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
16aa0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
16ab0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
16ac0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
16ad0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
16ae0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
16af0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
16b00 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
16b10 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
16b20 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
16b30 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
16b40 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
16b50 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
16b60 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
16b70 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
16b80 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
16b90 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16ba0 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
16bb0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
16bc0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
16bd0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
16be0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16bf0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16c00 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
16c10 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
16c20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
16c30 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
16c40 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
16c50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
16c60 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
16c70 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
16c80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
16c90 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
16ca0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
16cb0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
16cc0 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
16cd0 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
16ce0 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
16cf0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
16d00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
16d10 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
16d20 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
16d30 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
16d40 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
16d50 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
16d60 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
16d70 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
16d80 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
16d90 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
16da0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
16db0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
16dc0 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
16dd0 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
16de0 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
16df0 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
16e00 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
16e10 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
16e20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
16e30 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
16e40 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
16e50 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
16e60 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
16e70 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
16e80 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
16e90 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
16ea0 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
16eb0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
16ec0 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
16ed0 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
16ee0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16ef0 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
16f10 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
16f20 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
16f30 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
16f40 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
16f50 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
16f60 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
16f70 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
16f80 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
16f90 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
16fa0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
16fb0 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
16fc0 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
16fd0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
16fe0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
16ff0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17000 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
17010 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
17020 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
17030 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
17040 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
17050 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
17060 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
17070 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
17080 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
17090 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
170a0 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
170b0 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
170c0 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
170d0 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
170e0 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
170f0 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
17100 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
17110 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
17120 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
17130 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17140 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
17150 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
17160 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
17170 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
17180 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
17190 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
171a0 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
171b0 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
171c0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
171d0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
171e0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
171f0 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
17200 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
17210 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
17220 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
17230 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
17240 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
17250 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
17260 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
17270 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
17280 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
17290 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
172a0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
172b0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
172c0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
172d0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
172e0 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
172f0 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
17300 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
17310 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
17320 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
17330 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
17340 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
17350 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
17360 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
17370 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
17380 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
17390 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
173a0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
173b0 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
173c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
173d0 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
173e0 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
173f0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17400 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
17410 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
17420 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
17430 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
17440 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17450 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
17460 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
17470 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
17480 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
17490 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
174a0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
174b0 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
174c0 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
174d0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
174e0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
174f0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
17500 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
17510 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
17520 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
17530 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
17540 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
17550 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
17560 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
17570 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
17580 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
17590 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
175a0 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
175b0 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
175c0 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
175d0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
175e0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
175f0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17600 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
17610 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
17620 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
17630 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17640 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
17650 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
17660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17670 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
17680 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
17690 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
176a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
176b0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
176c0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
176d0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
176e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
176f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
17700 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
17710 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
17720 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
17730 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
17740 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
17750 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
17760 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
17770 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
17780 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
17790 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
177a0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
177b0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74  tibility..*/.int
177c0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
177d0 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73  d_result_codes(s
177e0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f  qlite3*, int ono
177f0 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ff);../*.** CAPI
17800 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72  3REF: Last Inser
17810 74 20 52 6f 77 69 64 0a 2a 2a 20 4d 45 54 48 4f  t Rowid.** METHO
17820 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
17830 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
17840 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c  most SQLite tabl
17850 65 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b  es (except for [
17860 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74  WITHOUT ROWID] t
17870 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20  ables).** has a 
17880 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
17890 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
178a0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
178b0 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
178c0 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
178d0 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
178e0 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
178f0 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
17900 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
17910 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
17920 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
17930 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
17940 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
17950 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
17960 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
17970 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
17980 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
17990 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
179a0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
179b0 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
179c0 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
179d0 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  wid..**.** ^The 
179e0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
179f0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74  ert_rowid(D) int
17a00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
17a10 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
17a20 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  e .** most recen
17a30 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  t successful [IN
17a40 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77  SERT] into a row
17a50 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72  id table or [vir
17a60 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f  tual table].** o
17a70 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
17a80 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73  ction D..** ^Ins
17a90 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f  erts into [WITHO
17aa0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
17ab0 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65   are not recorde
17ac0 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63  d..** ^If no suc
17ad0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17ae0 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62  s into rowid tab
17af0 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  les.** have ever
17b00 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65   occurred on the
17b10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17b20 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e  tion D, .** then
17b30 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
17b40 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65  sert_rowid(D) re
17b50 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
17b60 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52  * ^(If an [INSER
17b70 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  T] occurs within
17b80 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69   a trigger or wi
17b90 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20  thin a [virtual 
17ba0 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64  table].** method
17bb0 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  , then this rout
17bc0 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ine will return 
17bd0 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
17be0 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72  he inserted.** r
17bf0 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
17c00 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
17c10 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
17c20 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  d is running..**
17c30 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72   But once the tr
17c40 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17c50 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e   table method en
17c60 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  ds, the value re
17c70 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68  turned .** by th
17c80 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72  is routine rever
17c90 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61  ts to what it wa
17ca0 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69  s before the tri
17cb0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a  gger or virtual.
17cc0 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  ** table method 
17cd0 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  began.)^.**.** ^
17ce0 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74  An [INSERT] that
17cf0 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20   fails due to a 
17d00 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
17d10 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a  tion is not a.**
17d20 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
17d30 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f  ERT] and does no
17d40 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c  t change the val
17d50 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  ue returned by t
17d60 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20  his.** routine. 
17d70 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52   ^Thus INSERT OR
17d80 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52   FAIL, INSERT OR
17d90 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20   IGNORE, INSERT 
17da0 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20  OR ROLLBACK,.** 
17db0 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42  and INSERT OR AB
17dc0 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e  ORT make no chan
17dd0 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72  ges to the retur
17de0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a  n value of this.
17df0 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20  ** routine when 
17e00 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20  their insertion 
17e10 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49  fails.  ^(When I
17e20 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
17e30 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61  .** encounters a
17e40 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
17e50 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e  ation, it does n
17e60 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a  ot fail.  The.**
17e70 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65   INSERT continue
17e80 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  s to completion 
17e90 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72  after deleting r
17ea0 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a  ows that caused.
17eb0 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  ** the constrain
17ec0 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53  t problem so INS
17ed0 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77  ERT OR REPLACE w
17ee0 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67  ill always chang
17ef0 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20  e.** the return 
17f00 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e  value of this in
17f10 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a  terface.)^.**.**
17f20 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73   ^For the purpos
17f30 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  es of this routi
17f40 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  ne, an [INSERT] 
17f50 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  is considered to
17f60 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75  .** be successfu
17f70 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  l even if it is 
17f80 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c  subsequently rol
17f90 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  led back..**.** 
17fa0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73  This function is
17fb0 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53   accessible to S
17fc0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69  QL statements vi
17fd0 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69  a the.** [last_i
17fe0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51  nsert_rowid() SQ
17ff0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
18000 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
18010 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73   thread performs
18020 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20   a new [INSERT] 
18030 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  on the same.** d
18040 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18050 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71  on while the [sq
18060 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
18070 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75  t_rowid()].** fu
18080 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
18090 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67  g and thus chang
180a0 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65  es the last inse
180b0 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74  rt [rowid],.** t
180c0 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
180d0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
180e0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
180f0 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e  owid()] is.** un
18100 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18110 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20  might not equal 
18120 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f  either the old o
18130 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73  r the new.** las
18140 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
18150 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
18160 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  64 sqlite3_last_
18170 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
18180 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18190 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
181a0 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
181b0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
181c0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
181d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
181e0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
181f0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
18200 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
18210 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
18220 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
18230 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
18240 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18250 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
18260 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
18270 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
18280 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
18290 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
182a0 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
182b0 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
182c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
182d0 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
182e0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
182f0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
18300 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
18310 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
18320 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
18330 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
18340 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
18350 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
18360 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
18370 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
18380 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
18390 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
183a0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
183b0 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
183c0 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
183d0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
183e0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
183f0 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
18400 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
18410 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
18420 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
18430 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
18440 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
18450 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
18460 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
18470 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
18480 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
18490 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
184a0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
184b0 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
184c0 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
184d0 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
184e0 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
184f0 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
18500 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
18510 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
18520 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
18530 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
18540 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
18550 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
18560 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
18570 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
18580 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
18590 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
185a0 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
185b0 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
185c0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
185d0 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
185e0 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
185f0 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
18600 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
18610 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
18620 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
18630 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
18640 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
18650 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
18660 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
18670 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
18680 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
18690 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
186a0 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
186b0 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
186c0 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
186d0 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
186e0 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
186f0 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
18700 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
18710 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
18720 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
18730 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
18740 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
18750 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
18760 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
18770 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
18780 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
18790 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
187a0 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
187b0 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
187c0 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
187d0 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
187e0 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
187f0 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
18800 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
18810 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
18820 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
18830 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
18840 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
18850 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
18860 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
18870 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
18880 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
18890 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
188a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
188b0 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
188c0 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
188d0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
188e0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
188f0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
18900 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
18910 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
18920 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
18930 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
18940 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
18950 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
18960 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
18970 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
18980 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
18990 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
189a0 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
189b0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
189c0 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
189d0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
189e0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
189f0 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
18a00 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
18a10 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
18a20 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
18a30 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
18a40 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18a50 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
18a60 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
18a70 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
18a80 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
18a90 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
18aa0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18ab0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18ac0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
18ad0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18ae0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18af0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18b00 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
18b10 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
18b20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
18b30 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
18b40 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
18b50 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
18b60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
18b70 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
18b80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18b90 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
18ba0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
18bb0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
18bc0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
18bd0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
18be0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
18bf0 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
18c00 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
18c10 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
18c20 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
18c30 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
18c40 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
18c50 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
18c60 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18c70 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
18c80 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
18c90 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
18ca0 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
18cb0 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
18cc0 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
18cd0 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
18ce0 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
18cf0 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
18d00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
18d10 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18d20 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
18d30 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
18d40 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
18d50 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
18d60 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
18d70 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
18d80 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
18d90 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
18da0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
18db0 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
18dc0 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
18dd0 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
18de0 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
18df0 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
18e00 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
18e10 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
18e20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
18e30 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
18e40 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
18e50 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
18e60 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
18e70 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
18e80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
18e90 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
18ea0 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
18eb0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
18ec0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
18ed0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
18ee0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
18ef0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
18f00 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
18f10 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
18f20 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
18f30 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
18f40 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
18f50 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
18f60 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
18f70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
18f80 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
18f90 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
18fa0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
18fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
18fc0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
18fd0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
18fe0 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
18ff0 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
19000 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
19010 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
19020 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
19030 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
19040 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
19050 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
19060 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
19070 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
19080 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
19090 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
190a0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
190b0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
190c0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
190d0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
190e0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
190f0 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
19100 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
19110 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
19120 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
19130 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
19140 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
19150 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
19160 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
19170 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
19180 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
19190 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
191a0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
191b0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
191c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
191d0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
191e0 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
191f0 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
19200 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
19210 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
19220 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
19230 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
19240 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
19250 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
19260 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
19270 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
19280 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
19290 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
192a0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
192b0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
192c0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
192d0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
192e0 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
192f0 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
19300 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
19310 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
19320 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
19330 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
19340 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
19350 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
19360 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
19370 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
19380 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
19390 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
193a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
193b0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
193c0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
193d0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
193e0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
193f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
19400 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
19410 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
19420 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
19430 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
19440 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
19450 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
19460 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
19470 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
19480 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
19490 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
194a0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
194b0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
194c0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
194d0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
194e0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
194f0 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
19500 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
19510 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
19520 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
19530 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
19540 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
19550 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
19560 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
19570 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
19580 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
19590 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
195a0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
195b0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
195c0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
195d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
195e0 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
195f0 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
19600 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
19610 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
19620 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
19630 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
19640 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
19650 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
19660 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19670 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
19680 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
19690 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
196a0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
196b0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
196c0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
196d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
196e0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
196f0 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
19700 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
19710 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
19720 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
19730 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
19740 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
19750 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
19760 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
19770 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
19780 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
19790 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
197a0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
197b0 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
197c0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
197d0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
197e0 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
197f0 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
19800 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
19810 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
19820 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
19830 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
19840 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
19850 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
19860 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
19870 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
19880 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
19890 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
198a0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
198b0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
198c0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
198d0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
198e0 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
198f0 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
19900 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
19910 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
19920 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
19930 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
19940 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
19950 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
19960 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
19970 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
19980 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
19990 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
199a0 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
199b0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
199c0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
199d0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
199e0 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
199f0 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
19a00 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
19a10 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
19a20 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
19a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
19a40 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
19a50 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
19a60 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
19a70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
19a80 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
19a90 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
19aa0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
19ab0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
19ac0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
19ad0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
19ae0 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
19af0 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
19b00 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
19b10 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
19b20 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
19b30 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
19b40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
19b50 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
19b60 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
19b70 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19b80 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
19b90 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
19ba0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
19bb0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
19bc0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
19bd0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
19be0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
19bf0 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
19c00 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
19c10 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
19c20 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
19c30 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
19c40 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
19c50 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
19c60 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
19c70 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
19c80 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
19c90 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
19ca0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
19cb0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
19cc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
19cd0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
19ce0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
19cf0 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
19d00 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
19d10 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
19d20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
19d30 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
19d40 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
19d50 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
19d60 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
19d70 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
19d80 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
19d90 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
19da0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
19db0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
19dc0 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f   Errors.** KEYWO
19dd0 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c  RDS: {busy-handl
19de0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75  er callback} {bu
19df0 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d  sy handler}.** M
19e00 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19e10 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19e20 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
19e30 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
19e40 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
19e50 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
19e60 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
19e70 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
19e80 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
19e90 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
19ea0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
19eb0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
19ec0 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
19ed0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ee0 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
19ef0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19f00 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
19f10 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
19f20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
19f30 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
19f40 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
19f50 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
19f60 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
19f70 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
19f80 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
19f90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
19fa0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
19fb0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
19fc0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
19fd0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19fe0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19ff0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1a000 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1a010 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1a020 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1a030 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1a040 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1a050 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1a060 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1a070 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1a080 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1a090 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1a0a0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1a0b0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1a0c0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1a0d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1a0e0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1a0f0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1a100 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1a110 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1a120 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1a130 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1a140 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1a150 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72   been invoked pr
1a160 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65  eviously for the
1a170 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76   same locking ev
1a180 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  ent.  ^If the.**
1a190 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72   busy callback r
1a1a0 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e  eturns 0, then n
1a1b0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74  o additional att
1a1c0 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74  empts are made t
1a1d0 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20  o.** access the 
1a1e0 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51  database and [SQ
1a1f0 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65  LITE_BUSY] is re
1a200 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65  turned.** to the
1a210 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a   application..**
1a220 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1a230 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1a240 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1a250 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1a260 61 64 65 20 74 6f 20 61 63 63 65 73 73 20 74 68  ade to access th
1a270 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74  e database and t
1a280 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73  he cycle repeats
1a290 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73  ..**.** The pres
1a2a0 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68  ence of a busy h
1a2b0 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20  andler does not 
1a2c0 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69  guarantee that i
1a2d0 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65  t will be invoke
1a2e0 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20  d.** when there 
1a2f0 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69  is lock contenti
1a300 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64  on. ^If SQLite d
1a310 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69  etermines that i
1a320 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
1a330 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c  .** handler coul
1a340 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65  d result in a de
1a350 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20  adlock, it will 
1a360 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74  go ahead and ret
1a370 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
1a380 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c  ].** to the appl
1a390 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20  ication instead 
1a3a0 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
1a3b0 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72  .** busy handler
1a3c0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
1a3d0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
1a3e0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
1a3f0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
1a400 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
1a410 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
1a420 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
1a430 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
1a440 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
1a450 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
1a460 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
1a470 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
1a480 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
1a490 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
1a4a0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1a4b0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
1a4c0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
1a4d0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
1a4e0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
1a4f0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
1a500 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
1a510 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1a520 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
1a530 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
1a540 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
1a550 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1a560 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
1a570 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
1a580 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
1a590 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
1a5a0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
1a5b0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
1a5c0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
1a5d0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
1a5e0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
1a5f0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
1a600 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
1a610 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
1a620 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1a630 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
1a640 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
1a650 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
1a660 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s NULL..**.** ^(
1a670 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
1a680 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
1a690 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20  handler defined 
1a6a0 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74  for each.** [dat
1a6b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a6c0 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65  ].  Setting a ne
1a6d0 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  w busy handler c
1a6e0 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65  lears any.** pre
1a6f0 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64  viously set hand
1a700 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68  ler.)^  ^Note th
1a710 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  at calling [sqli
1a720 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1a730 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61  ()].** or evalua
1a740 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73  ting [PRAGMA bus
1a750 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c  y_timeout=N] wil
1a760 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  l change the.** 
1a770 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64  busy handler and
1a780 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20   thus clear any 
1a790 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62  previously set b
1a7a0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
1a7b0 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
1a7c0 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
1a7d0 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
1a7e0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
1a7f0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
1a800 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
1a810 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1a820 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65  andler.  In othe
1a830 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20  r words,.** the 
1a840 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1a850 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20  not reentrant.  
1a860 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73  Any such actions
1a870 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  .** result in un
1a880 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72  defined behavior
1a890 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20  ..** .** A busy 
1a8a0 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74  handler must not
1a8b0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
1a8c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a8d0 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73  * or [prepared s
1a8e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
1a8f0 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20  nvoked the busy 
1a900 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20  handler..*/.int 
1a910 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1a920 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1a930 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1a940 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1a950 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1a960 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1a970 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1a980 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1a990 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1a9a0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1a9b0 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1a9c0 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1a9d0 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1a9e0 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1a9f0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1aa00 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1aa10 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1aa20 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1aa30 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1aa40 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1aa50 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1aa60 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1aa70 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1aa80 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1aa90 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1aaa0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1aab0 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1aac0 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1aad0 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1aae0 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1aaf0 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  _BUSY]..**.** ^C
1ab00 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1ab10 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1ab20 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1ab30 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1ab40 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1ab50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1ab60 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1ab70 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1ab80 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1ab90 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1aba0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1abb0 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79  nnection] at any
1abc0 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20   given moment.  
1abd0 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20  If another busy 
1abe0 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64  handler.** was d
1abf0 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b  efined  (using [
1ac00 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1ac10 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74  dler()]) prior t
1ac20 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69  o calling.** thi
1ac30 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20  s routine, that 
1ac40 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1ac50 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e  er is cleared.)^
1ac60 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1ac70 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74    [PRAGMA busy_t
1ac80 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73  imeout].*/.int s
1ac90 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1aca0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1acb0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1acc0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1acd0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1ace0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1acf0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1ad00 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1ad10 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1ad20 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1ad30 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1ad40 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1ad50 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1ad60 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1ad70 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1ad80 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1ad90 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1ada0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1adb0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1adc0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1add0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1ade0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1adf0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1ae00 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1ae10 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1ae20 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1ae30 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1ae40 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1ae50 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1ae60 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1ae70 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1ae80 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1ae90 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1aea0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1aeb0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1aec0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1aed0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1aee0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1aef0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1af00 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1af10 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1af20 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1af30 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1af40 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1af50 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1af60 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1af70 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1af80 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1af90 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1afa0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1afb0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1afc0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1afd0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1afe0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1aff0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1b000 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1b010 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1b020 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1b030 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1b040 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1b050 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1b060 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1b070 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1b080 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1b090 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b0a0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1b0b0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1b0c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1b0d0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1b0e0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1b0f0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1b100 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1b110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1b120 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1b130 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1b140 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1b150 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1b160 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1b170 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1b180 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1b190 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1b1a0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1b1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1b1c0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1b1d0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1b1e0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1b1f0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1b200 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b210 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b220 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1b230 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1b240 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1b250 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1b260 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1b270 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1b280 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1b290 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1b2a0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1b2b0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1b2c0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b2d0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1b2e0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1b2f0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1b300 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1b310 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1b320 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1b330 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1b340 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1b350 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1b360 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1b370 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1b380 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1b390 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1b3a0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1b3b0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b3c0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1b3d0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b3e0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1b3f0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1b400 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1b410 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1b420 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1b430 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1b440 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1b450 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1b460 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1b470 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1b480 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b490 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1b4a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b4b0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1b4c0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1b4d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1b4e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1b4f0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1b500 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1b510 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1b520 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1b530 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1b540 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1b550 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1b560 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1b570 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1b580 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1b590 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1b5a0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1b5b0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1b5c0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1b5d0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1b5e0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1b5f0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1b600 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1b610 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1b620 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1b630 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1b640 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1b650 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1b660 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1b670 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1b680 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1b690 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1b6a0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1b6b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1b6c0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1b6d0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1b6e0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1b6f0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1b700 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1b710 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b720 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1b730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1b740 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1b750 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1b760 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1b770 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1b780 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1b790 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1b7a0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1b7b0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1b7c0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1b7d0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1b7e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1b7f0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1b800 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1b810 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1b820 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1b830 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1b840 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1b850 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1b860 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1b870 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1b880 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1b890 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1b8a0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1b8b0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1b8c0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1b8d0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1b8e0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1b8f0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1b900 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1b910 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1b920 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1b930 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1b940 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b950 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1b960 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1b970 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1b980 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1b990 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1b9a0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1b9b0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1b9c0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1b9d0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1b9e0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1b9f0 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1ba00 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1ba10 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1ba20 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1ba30 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1ba40 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1ba50 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1ba60 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1ba70 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1ba80 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1ba90 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1baa0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1bab0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1bac0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1bad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1bae0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1baf0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1bb00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1bb10 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1bb20 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1bb30 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1bb40 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1bb50 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1bb60 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1bb70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1bb80 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1bb90 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1bba0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1bbb0 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1bbc0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1bbd0 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1bbe0 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1bbf0 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1bc00 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1bc10 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1bc20 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1bc30 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1bc40 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1bc50 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1bc60 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1bc70 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1bc80 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1bc90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1bca0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1bcb0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1bcc0 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1bcd0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1bce0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1bcf0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1bd00 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1bd10 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1bd20 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1bd30 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1bd40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1bd50 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1bd60 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1bd70 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1bd80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1bd90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1bda0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1bdb0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1bdc0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1bdd0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1bde0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1bdf0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1be00 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1be10 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1be20 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1be30 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1be40 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1be50 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1be60 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1be70 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1be80 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1be90 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1bea0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1beb0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1bec0 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1bed0 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1bee0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1bef0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1bf00 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1bf10 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1bf20 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1bf30 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1bf40 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1bf50 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1bf60 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1bf70 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1bf80 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1bf90 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1bfa0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1bfb0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1bfc0 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1bfd0 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1bfe0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1bff0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1c000 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1c010 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1c020 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1c030 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1c040 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1c050 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1c060 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1c070 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1c080 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1c090 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1c0a0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1c0b0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1c0c0 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1c0d0 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1c0e0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1c0f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1c100 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1c110 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1c120 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1c130 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1c140 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1c150 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1c160 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1c170 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1c180 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1c190 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1c1a0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1c1b0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1c1c0 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1c1d0 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1c1e0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1c1f0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1c200 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1c210 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1c220 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1c230 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1c240 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1c250 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1c260 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1c270 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1c280 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1c290 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1c2a0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1c2b0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1c2c0 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1c2d0 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1c2e0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1c2f0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1c300 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1c310 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1c320 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1c330 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1c340 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1c350 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1c360 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1c370 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1c380 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1c390 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1c3a0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1c3b0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1c3c0 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1c3d0 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1c3e0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1c3f0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1c400 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1c410 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1c420 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1c430 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1c440 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1c450 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1c460 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1c470 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1c480 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1c490 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1c4a0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1c4b0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1c4c0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c4d0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c4e0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1c4f0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1c500 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1c510 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1c520 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1c530 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1c540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1c550 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1c560 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c570 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c580 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c590 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c5a0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1c5b0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1c5c0 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1c5d0 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1c5e0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1c5f0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1c600 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1c610 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1c620 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1c630 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1c640 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1c650 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1c660 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1c670 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1c680 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1c690 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1c6a0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1c6b0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1c6c0 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1c6d0 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1c6e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c6f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1c700 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1c710 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1c720 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1c730 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1c740 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1c750 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1c760 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c770 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1c780 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1c790 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1c7a0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1c7b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c7c0 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1c7d0 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1c7e0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1c7f0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1c800 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1c810 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1c820 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1c830 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1c840 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1c850 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1c860 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1c870 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1c880 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1c890 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1c8a0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1c8b0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1c8c0 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1c8d0 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1c8e0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1c8f0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1c900 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1c910 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1c920 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1c930 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1c940 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1c950 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1c960 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1c970 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1c980 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1c990 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1c9a0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1c9b0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1c9c0 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1c9d0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1c9e0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1c9f0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1ca00 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1ca10 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1ca20 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1ca30 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1ca40 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1ca50 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1ca60 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1ca70 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1ca80 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1ca90 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1caa0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1cab0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1cac0 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
1cad0 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
1cae0 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
1caf0 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
1cb00 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
1cb10 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
1cb20 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
1cb30 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
1cb40 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
1cb50 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
1cb60 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
1cb70 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
1cb80 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
1cb90 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1cba0 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
1cbb0 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
1cbc0 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
1cbd0 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
1cbe0 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
1cbf0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1cc00 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1cc10 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1cc20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1cc30 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1cc40 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1cc50 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1cc60 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1cc70 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1cc80 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1cc90 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1cca0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1ccb0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1ccc0 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d  .char *sqlite3_m
1ccd0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1cce0 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73  r*,...);.char *s
1ccf0 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1cd00 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1cd10 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71 6c  list);.char *sql
1cd20 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e  ite3_snprintf(in
1cd30 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
1cd40 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72 20  ar*, ...);.char 
1cd50 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e  *sqlite3_vsnprin
1cd60 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e  tf(int,char*,con
1cd70 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1cd80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1cd90 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1cda0 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d  cation Subsystem
1cdb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  .**.** The SQLit
1cdc0 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73  e core uses thes
1cdd0 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73  e three routines
1cde0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
1cdf0 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20  own.** internal 
1ce00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1ce10 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20  n needs. "Core" 
1ce20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
1ce30 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73  sentence.** does
1ce40 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65   not include ope
1ce50 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
1ce60 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65  ecific VFS imple
1ce70 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a  mentation.  The.
1ce80 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75  ** Windows VFS u
1ce90 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f  ses native mallo
1cea0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
1ceb0 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f  or some operatio
1cec0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
1ced0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1cee0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1cef0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62  a pointer to a b
1cf00 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72  lock.** of memor
1cf10 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  y at least N byt
1cf20 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68  es in length, wh
1cf30 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72  ere N is the par
1cf40 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73  ameter..** ^If s
1cf50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1cf60 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74  is unable to obt
1cf70 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66  ain sufficient f
1cf80 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69  ree.** memory, i
1cf90 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  t returns a NULL
1cfa0 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74   pointer.  ^If t
1cfb0 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74  he parameter N t
1cfc0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  o.** sqlite3_mal
1cfd0 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72  loc() is zero or
1cfe0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73   negative then s
1cff0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1d000 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c  returns.** a NUL
1d010 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1d020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1d030 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e  lloc64(N) routin
1d040 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b  e works just lik
1d050 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  e.** sqlite3_mal
1d060 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20 74 68  loc(N) except th
1d070 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67  at N is an unsig
1d080 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ned 64-bit integ
1d090 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  er instead.** of
1d0a0 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74   a signed 32-bit
1d0b0 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20   integer..**.** 
1d0c0 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1d0d0 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1d0e0 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1d0f0 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1d100 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1d110 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1d120 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1d130 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1d140 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1d150 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1d160 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1d170 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1d180 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1d190 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1d1a0 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1d1b0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1d1c0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1d1d0 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1d1e0 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1d1f0 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1d200 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1d210 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1d220 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1d230 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1d240 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1d250 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1d260 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1d270 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1d280 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1d290 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1d2a0 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1d2b0 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1d2c0 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1d2d0 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1d2e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1d2f0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1d300 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1d310 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1d320 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1d330 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1d340 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1d350 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
1d360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1d370 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  ,N) interface at
1d380 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1d390 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1d3a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20  ry allocation X 
1d3b0 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1d3c0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
1d3d0 68 65 20 58 20 70 61 72 61 6d 65 74 65 72 20 74  he X parameter t
1d3e0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d3f0 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e  c(X,N).** is a N
1d400 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1d410 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73   its behavior is
1d420 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61   identical to ca
1d430 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1d440 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e  _malloc(N)..** ^
1d450 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  If the N paramet
1d460 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1d470 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65  alloc(X,N) is ze
1d480 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1d490 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1d4a0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1d4b0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1d4c0 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1d4d0 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  ee(X)..** ^sqlit
1d4e0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1d4f0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1d500 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1d510 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1d520 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1d530 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1d540 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20  if insufficient 
1d550 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61  memory is availa
1d560 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1d570 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1d580 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d590 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1d5a0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1d5b0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1d5c0 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1d5d0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1d5e0 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1d5f0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1d600 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e  _realloc(X,N) an
1d610 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1d620 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1d630 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1d640 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74  realloc(X,N) ret
1d650 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  urns NULL and N 
1d660 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65  is positive, the
1d670 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61  n the.** prior a
1d680 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74  llocation is not
1d690 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54   freed..**.** ^T
1d6a0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1d6b0 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66  oc64(X,N) interf
1d6c0 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73  aces works the s
1d6d0 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65  ame as.** sqlite
1d6e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65  3_realloc(X,N) e
1d6f0 78 63 65 70 74 20 74 68 61 74 20 4e 20 69 73 20  xcept that N is 
1d700 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 64-bit unsigne
1d710 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61  d integer instea
1d720 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74  d.** of a 32-bit
1d730 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e   signed integer.
1d740 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20  .**.** ^If X is 
1d750 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1d760 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  ion previously o
1d770 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1d780 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a  ite3_malloc(),.*
1d790 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1d7a0 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  64(), sqlite3_re
1d7b0 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69  alloc(), or sqli
1d7c0 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c  te3_realloc64(),
1d7d0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
1d7e0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
1d7f0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1d800 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  at memory alloca
1d810 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a  tion in bytes..*
1d820 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74  * ^The value ret
1d830 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1d840 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20  _msize(X) might 
1d850 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74  be larger than t
1d860 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20  he number.** of 
1d870 62 79 74 65 73 20 72 65 71 75 65 73 74 65 64 20  bytes requested 
1d880 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63  when X was alloc
1d890 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20  ated.  ^If X is 
1d8a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1d8b0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1d8c0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1d8d0 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e  zero.  If X poin
1d8e0 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20  ts to something 
1d8f0 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74  that is not.** t
1d900 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1d910 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d920 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e  n, or if it poin
1d930 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79  ts to a formerly
1d940 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79  .** valid memory
1d950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74   allocation that
1d960 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72   has now been fr
1d970 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  eed, then the be
1d980 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c  havior.** of sql
1d990 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73  ite3_msize(X) is
1d9a0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
1d9b0 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e  ossibly harmful.
1d9c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1d9d0 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1d9e0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
1d9f0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1da00 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  (),.** sqlite3_m
1da10 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73  alloc64(), and s
1da20 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1da30 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1da40 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1da50 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1da60 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1da70 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1da80 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1da90 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1daa0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1dab0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1dac0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1dad0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1dae0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1daf0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1db00 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1db10 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1db20 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1db30 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1db40 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1db50 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1db60 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1db70 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1db80 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1db90 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1dba0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1dbb0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1dbc0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1dbd0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1dbe0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1dbf0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1dc00 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1dc10 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1dc20 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1dc30 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1dc40 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1dc50 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1dc60 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1dc70 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1dc80 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1dc90 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1dca0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1dcb0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1dcc0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1dcd0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1dce0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1dcf0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1dd00 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1dd10 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1dd20 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1dd30 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1dd40 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1dd50 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1dd60 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1dd70 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1dd80 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1dd90 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1dda0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1ddb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1ddc0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1ddd0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1dde0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1ddf0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1de00 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1de10 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1de20 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1de30 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1de40 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1de50 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1de60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1de70 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1de80 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1de90 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1dea0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1deb0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1dec0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1ded0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1dee0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1def0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1df00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1df10 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20  lloc(int);.void 
1df20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36  *sqlite3_malloc6
1df30 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  4(sqlite3_uint64
1df40 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  );.void *sqlite3
1df50 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1df60 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69  int);.void *sqli
1df70 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
1df80 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
1df90 74 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  t64);.void sqlit
1dfa0 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1dfb0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73  sqlite3_uint64 s
1dfc0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69  qlite3_msize(voi
1dfd0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1dfe0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1dff0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1e000 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1e010 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1e020 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1e030 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1e040 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1e050 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1e060 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1e070 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1e080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1e090 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1e0a0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1e0b0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1e0c0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1e0d0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1e0e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e0f0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1e100 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1e110 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1e120 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1e130 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1e140 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1e150 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1e160 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1e170 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1e180 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1e190 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1e1a0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1e1b0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1e1c0 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1e1d0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1e1e0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1e1f0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1e200 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1e210 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1e220 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e230 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1e240 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1e250 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1e260 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1e270 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1e280 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1e290 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1e2a0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1e2b0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1e2c0 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1e2d0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1e2e0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1e2f0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1e300 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1e310 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1e320 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1e330 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1e340 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1e350 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1e360 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1e370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1e380 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1e390 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1e3a0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1e3b0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1e3c0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1e3d0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1e3e0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1e3f0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1e400 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1e410 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1e420 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1e430 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
1e440 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1e450 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1e460 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1e470 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e480 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1e490 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1e4a0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1e4b0 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1e4c0 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1e4d0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1e4e0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1e4f0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1e500 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1e510 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1e520 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1e530 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1e540 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1e550 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1e560 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1e570 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1e580 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1e590 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1e5a0 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1e5b0 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1e5c0 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1e5d0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1e5e0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1e5f0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1e600 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1e610 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1e620 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1e630 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1e640 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1e650 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1e660 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61  ..** ^The P para
1e670 6d 65 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e  meter can be a N
1e680 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1e690 2a 2a 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74  ** ^If this rout
1e6a0 69 6e 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e  ine has not been
1e6b0 20 70 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c   previously call
1e6c0 65 64 20 6f 72 20 69 66 20 74 68 65 20 70 72 65  ed or if the pre
1e6d0 76 69 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61  vious.** call ha
1e6e0 64 20 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e  d N less than on
1e6f0 65 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e or a NULL poin
1e700 74 65 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20  ter for P, then 
1e710 74 68 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73  the PRNG is.** s
1e720 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64  eeded using rand
1e730 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20  omness obtained 
1e740 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1e750 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a  ness method of.*
1e760 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  * the default [s
1e770 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
1e780 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  ct..** ^If the p
1e790 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
1e7a0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64  this routine had
1e7b0 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f   an N of 1 or mo
1e7c0 72 65 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d  re and a.** non-
1e7d0 4e 55 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20  NULL P then the 
1e7e0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
1e7f0 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
1e800 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
1e810 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
1e820 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
1e830 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
1e840 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
1e850 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61  .void sqlite3_ra
1e860 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20  ndomness(int N, 
1e870 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a  void *P);../*.**
1e880 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69   CAPI3REF: Compi
1e890 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a  le-Time Authoriz
1e8a0 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
1e8b0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1e8c0 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1e8d0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1e8e0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1e8f0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1e900 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1e910 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e920 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1e930 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1e940 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1e950 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e960 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1e970 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1e980 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1e990 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1e9a0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1e9b0 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1e9c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1e9d0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1e9e0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1e9f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ea00 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1ea10 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1ea20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
1ea30 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
1ea40 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
1ea50 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
1ea60 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
1ea70 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
1ea80 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea90 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
1eaa0 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
1eab0 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
1eac0 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
1ead0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
1eae0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
1eaf0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
1eb00 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
1eb10 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1eb20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
1eb30 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
1eb40 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
1eb50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
1eb60 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
1eb70 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
1eb80 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
1eb90 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
1eba0 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
1ebb0 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
1ebc0 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
1ebd0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
1ebe0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
1ebf0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
1ec00 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
1ec10 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
1ec20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
1ec30 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
1ec40 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
1ec50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ec60 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1ec70 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1ec80 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
1ec90 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1eca0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1ecb0 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
1ecc0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1ecd0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
1ece0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
1ecf0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
1ed00 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
1ed10 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
1ed20 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1ed30 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
1ed40 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
1ed50 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1ed60 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1ed70 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
1ed80 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
1ed90 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1eda0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
1edb0 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
1edc0 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
1edd0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
1ede0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1edf0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ee00 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
1ee10 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
1ee20 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
1ee30 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
1ee40 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
1ee50 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
1ee60 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
1ee70 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1ee80 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
1ee90 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
1eea0 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
1eeb0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
1eec0 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
1eed0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1eee0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
1eef0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
1ef00 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
1ef10 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
1ef20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1ef30 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
1ef40 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
1ef50 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
1ef60 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
1ef70 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
1ef80 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1ef90 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1efa0 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
1efb0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1efc0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
1efd0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
1efe0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1eff0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
1f000 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
1f010 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
1f020 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
1f030 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
1f040 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
1f050 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
1f060 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
1f070 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
1f080 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
1f090 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
1f0a0 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
1f0b0 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
1f0c0 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
1f0d0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
1f0e0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
1f0f0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
1f100 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
1f110 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
1f120 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
1f130 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1f140 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
1f150 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
1f160 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
1f170 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
1f180 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
1f190 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
1f1a0 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
1f1b0 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
1f1c0 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
1f1d0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
1f1e0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
1f1f0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
1f200 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
1f210 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
1f220 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
1f230 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
1f240 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
1f250 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
1f260 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
1f270 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
1f280 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
1f290 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
1f2a0 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
1f2b0 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
1f2c0 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
1f2d0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
1f2e0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
1f2f0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
1f300 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
1f310 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
1f320 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
1f330 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
1f340 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
1f350 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
1f360 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
1f370 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
1f380 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
1f390 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
1f3a0 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
1f3b0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
1f3c0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
1f3d0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
1f3e0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
1f3f0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
1f400 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
1f410 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1f420 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
1f430 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
1f440 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
1f450 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
1f460 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
1f470 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
1f480 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
1f490 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
1f4a0 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
1f4b0 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
1f4c0 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
1f4d0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
1f4e0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
1f4f0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
1f500 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
1f510 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
1f520 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
1f530 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
1f540 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
1f550 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
1f560 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
1f570 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
1f580 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
1f590 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1f5a0 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
1f5b0 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
1f5c0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
1f5d0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
1f5e0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
1f5f0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
1f600 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
1f610 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
1f620 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
1f630 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
1f640 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
1f650 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
1f660 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
1f670 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1f680 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1f690 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1f6a0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1f6b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1f6c0 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
1f6d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
1f6e0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
1f6f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1f700 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
1f710 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
1f720 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
1f730 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f740 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
1f750 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
1f760 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
1f770 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
1f780 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1f790 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
1f7a0 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
1f7b0 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
1f7c0 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
1f7d0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
1f7e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
1f7f0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
1f800 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
1f810 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
1f820 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
1f830 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
1f840 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
1f850 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1f860 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
1f870 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
1f880 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
1f890 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
1f8a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1f8b0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
1f8c0 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
1f8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
1f8e0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
1f8f0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
1f900 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
1f910 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
1f920 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
1f930 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
1f940 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
1f950 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
1f960 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
1f970 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
1f980 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
1f990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
1f9a0 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
1f9b0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
1f9c0 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
1f9d0 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ange..*/.int sql
1f9e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f9f0 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
1fa00 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
1fa10 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
1fa20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1fa30 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1fa40 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
1fa50 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
1fa60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fa70 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
1fa80 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
1fa90 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1faa0 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
1fab0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fac0 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
1fad0 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
1fae0 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
1faf0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
1fb00 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
1fb10 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
1fb20 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
1fb30 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
1fb40 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
1fb50 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
1fb60 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1fb70 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
1fb80 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
1fb90 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
1fba0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
1fbb0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
1fbc0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
1fbd0 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
1fbe0 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
1fbf0 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
1fc00 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
1fc10 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
1fc20 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
1fc30 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
1fc40 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
1fc50 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
1fc60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1fc70 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
1fc80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fc90 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
1fca0 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
1fcb0 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
1fcc0 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
1fcd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fce0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
1fcf0 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
1fd00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
1fd10 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
1fd20 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
1fd30 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
1fd40 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
1fd50 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
1fd60 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
1fd70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
1fd80 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
1fd90 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
1fda0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
1fdb0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
1fdc0 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
1fdd0 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
1fde0 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
1fdf0 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
1fe00 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
1fe10 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
1fe20 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1fe30 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
1fe40 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
1fe50 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
1fe60 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
1fe70 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
1fe80 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
1fe90 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
1fea0 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
1feb0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
1fec0 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
1fed0 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
1fee0 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
1fef0 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
1ff00 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
1ff10 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
1ff20 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
1ff30 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ff40 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
1ff50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ff60 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
1ff70 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1ff80 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
1ff90 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
1ffa0 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
1ffb0 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
1ffc0 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
1ffd0 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
1ffe0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
1fff0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
20000 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
20010 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
20020 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
20030 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
20040 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
20050 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
20060 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
20070 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
20080 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
20090 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
200a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
200b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
200c0 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
200d0 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
200e0 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
200f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
20100 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
20110 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
20120 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
20130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20140 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
20150 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
20160 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20170 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20190 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
201a0 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
201b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
201c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
201d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201e0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
201f0 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
20200 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
20210 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
20220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20230 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
20240 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
20250 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
20260 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
20270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20280 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
20290 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
202a0 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
202b0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
202c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
202d0 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
202e0 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
202f0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
20300 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
20310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
20320 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
20330 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
20340 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
20350 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
20370 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
20380 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
20390 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
203a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
203b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
203c0 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
203d0 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
203e0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
203f0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
20400 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
20410 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
20420 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
20430 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20440 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20450 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
20460 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
20470 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
20480 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
20490 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
204a0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
204b0 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
204c0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
204d0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
204e0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
204f0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
20500 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
20510 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
20520 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
20530 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20540 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
20550 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
20560 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
20570 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20580 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
20590 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
205a0 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
205b0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
205c0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
205d0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
205e0 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
205f0 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
20600 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
20610 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20630 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
20640 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
20650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20660 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
20670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20680 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
20690 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
206a0 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
206b0 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
206c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
206d0 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
206e0 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
206f0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
20700 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
20710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20720 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
20730 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
20740 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
20750 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20770 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
20780 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
20790 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
207a0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
207b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
207c0 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
207d0 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
207e0 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
207f0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
20800 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
20810 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
20820 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
20830 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
20840 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
20850 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
20860 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
20870 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
20880 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
20890 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
208a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
208b0 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
208c0 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
208d0 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
208e0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
208f0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
20900 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
20910 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
20920 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
20930 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
20940 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
20950 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
20960 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
20970 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
20980 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
20990 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
209a0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
209b0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
209c0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
209d0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
209e0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
209f0 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
20a00 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
20a10 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
20a20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20a30 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
20a40 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
20a50 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
20a60 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
20a70 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
20a80 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
20a90 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
20aa0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
20ab0 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
20ac0 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
20ad0 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
20ae0 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
20af0 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
20b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20b10 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
20b20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
20b30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20b40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
20b50 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
20b60 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
20b70 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
20b80 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
20b90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
20ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
20bb0 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
20bc0 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
20bd0 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
20be0 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
20bf0 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
20c00 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
20c10 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
20c20 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
20c30 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
20c40 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
20c50 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
20c60 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
20c70 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
20c80 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
20c90 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
20ca0 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
20cb0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
20cc0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
20cd0 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
20ce0 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
20cf0 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
20d00 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
20d10 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
20d20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
20d30 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
20d40 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
20d50 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
20d60 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
20d70 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
20d80 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
20d90 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
20da0 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
20db0 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
20dc0 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
20dd0 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
20de0 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
20df0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
20e00 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49 54  TRACE_SIZE_LIMIT
20e10 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
20e20 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
20e30 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74 68  d to limit.** th
20e40 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f 75  e length of [bou
20e50 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65 78  nd parameter] ex
20e60 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20 6f  pansion in the o
20e70 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65 33  utput of sqlite3
20e80 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  _trace()..**.** 
20e90 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
20ea0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
20eb0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
20ec0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
20ed0 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
20ee0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
20ef0 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
20f00 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
20f10 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
20f20 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
20f30 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
20f40 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
20f50 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
20f60 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
20f70 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
20f80 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
20f90 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
20fa0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
20fb0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
20fc0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
20fd0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
20fe0 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
20ff0 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
21000 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
21010 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
21020 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
21030 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
21040 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
21050 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
21060 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
21070 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
21080 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
21090 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
210a0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
210b0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
210c0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
210d0 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
210e0 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
210f0 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
21100 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
21110 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21120 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
21130 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
21140 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
21150 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
21160 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
21170 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
21180 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
21190 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
211a0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
211b0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
211c0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
211d0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
211e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
211f0 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
21200 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48  allbacks.** METH
21210 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
21220 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
21230 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
21240 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
21250 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
21260 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
21270 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
21280 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
21290 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
212a0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
212b0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
212c0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
212d0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
212e0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
212f0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
21300 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
21310 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
21320 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
21330 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
21340 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
21350 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
21360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
21370 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
21380 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
21390 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
213a0 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
213b0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
213c0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
213d0 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
213e0 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
213f0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
21400 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
21410 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
21420 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
21430 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
21440 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
21450 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
21460 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
21470 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
21480 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
21490 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
214a0 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
214b0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
214c0 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
214d0 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
214e0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
214f0 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
21500 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
21510 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
21520 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
21530 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
21540 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
21550 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
21560 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
21570 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
21580 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
21590 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
215a0 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
215b0 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
215c0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
215d0 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
215e0 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
215f0 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
21600 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
21610 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
21620 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
21630 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
21640 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
21650 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
21660 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
21670 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
21680 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
21690 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
216a0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
216b0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
216c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
216d0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
216e0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
216f0 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
21700 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
21710 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
21720 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
21730 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21740 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
21750 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
21760 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
21770 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
21780 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
21790 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
217a0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
217b0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
217c0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
217d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
217e0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
217f0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
21800 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
21810 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
21820 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
21830 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
21840 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
21850 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
21860 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
21870 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
21880 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
21890 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
218a0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
218b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
218c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
218d0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
218e0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
218f0 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
21900 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
21910 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
21920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21930 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
21940 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
21950 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
21960 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
21970 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
21980 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
21990 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
219a0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
219b0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
219c0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
219d0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
219e0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
219f0 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
21a00 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
21a10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
21a20 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
21a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
21a40 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
21a50 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
21a60 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
21a70 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
21a80 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
21a90 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
21aa0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
21ab0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
21ac0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
21ad0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
21ae0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
21af0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
21b00 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
21b10 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
21b20 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
21b30 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
21b40 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
21b50 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
21b60 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
21b70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
21b80 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
21b90 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
21ba0 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
21bb0 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
21bc0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21bd0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
21be0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
21bf0 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
21c00 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
21c10 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
21c20 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
21c30 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
21c40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
21c50 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
21c60 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
21c70 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
21c80 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
21c90 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
21ca0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
21cb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
21cc0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
21cd0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
21ce0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
21cf0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
21d00 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
21d10 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
21d20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21d30 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
21d40 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
21d50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
21d60 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
21d70 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
21d80 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
21d90 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
21da0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
21db0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
21dc0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
21dd0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
21de0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
21df0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
21e00 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
21e10 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
21e20 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
21e30 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
21e40 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
21e50 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
21e60 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
21e70 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
21e80 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
21e90 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
21ea0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
21eb0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
21ec0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
21ed0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
21ee0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
21ef0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21f00 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
21f10 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
21f20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
21f30 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
21f40 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
21f50 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
21f60 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
21f70 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
21f80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
21f90 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21fa0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
21fb0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
21fc0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21fd0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
21fe0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
21ff0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
22000 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
22010 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
22020 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
22030 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
22040 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
22050 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
22060 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
22070 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
22080 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
22090 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
220a0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
220b0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
220c0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
220d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
220e0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
220f0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
22100 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
22110 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
22120 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
22130 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
22140 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
22150 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
22160 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
22170 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
22180 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
22190 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
221a0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
221b0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
221c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
221d0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
221e0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
221f0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
22200 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
22210 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
22220 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
22230 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
22240 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
22250 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
22260 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
22270 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
22280 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
22290 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
222a0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
222b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
222c0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
222d0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
222e0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
222f0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
22300 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
22310 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
22320 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
22330 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
22340 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
22350 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
22360 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
22370 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22380 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
22390 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
223a0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
223b0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
223c0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
223d0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
223e0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
223f0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
22400 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
22410 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
22420 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
22430 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
22440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
22450 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
22460 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
22470 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
22480 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
22490 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
224a0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
224b0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
224c0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
224d0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
224e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
224f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
22500 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
22510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22520 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
22530 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
22540 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
22550 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
22560 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
22570 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
22580 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
22590 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
225a0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
225b0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
225c0 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
225d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
225e0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
225f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
22600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22610 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
22620 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
22630 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
22640 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
22650 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
22660 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
22670 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
22680 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
22690 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
226a0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
226b0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
226c0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
226d0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
226e0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
226f0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
22700 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
22710 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
22720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22730 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
22740 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
22750 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
22760 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
22770 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
22780 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
22790 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
227a0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
227b0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
227c0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
227d0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
227e0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
227f0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
22800 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
22810 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
22820 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
22830 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
22840 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
22850 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
22860 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
22870 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
22880 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
22890 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
228a0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
228b0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
228c0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
228d0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
228e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
228f0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
22900 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
22910 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
22920 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
22930 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
22940 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
22950 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
22960 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
22970 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
22980 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
22990 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
229a0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
229b0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
229c0 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
229d0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
229e0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
229f0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22a00 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
22a10 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
22a20 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
22a30 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
22a40 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
22a50 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
22a60 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
22a70 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
22a80 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
22a90 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
22aa0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
22ab0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
22ac0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
22ad0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
22ae0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
22af0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
22b00 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
22b10 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
22b20 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
22b30 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
22b40 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
22b50 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22b60 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
22b70 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
22b80 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
22b90 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
22ba0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
22bb0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
22bc0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
22bd0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
22be0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
22bf0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
22c00 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
22c10 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
22c20 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
22c30 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
22c40 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
22c50 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
22c60 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
22c70 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
22c80 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
22c90 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
22ca0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
22cb0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
22cc0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
22cd0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
22ce0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
22cf0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
22d00 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
22d10 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
22d20 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
22d30 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
22d40 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
22d50 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
22d60 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
22d70 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
22d80 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
22d90 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
22da0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
22db0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
22dc0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
22dd0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
22de0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
22df0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
22e00 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
22e10 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
22e20 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
22e30 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
22e40 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
22e50 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
22e60 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
22e70 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
22e80 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
22e90 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
22ea0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
22eb0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
22ec0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
22ed0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
22ee0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
22ef0 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
22f00 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
22f10 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
22f20 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
22f30 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
22f40 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
22f50 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
22f60 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
22f70 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
22f80 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
22f90 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
22fa0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
22fb0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
22fc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
22fd0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
22fe0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
22ff0 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
23000 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
23010 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
23020 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
23030 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
23040 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
23050 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
23060 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
23070 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
23080 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
23090 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
230a0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
230b0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
230c0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
230d0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
230e0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
230f0 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
23100 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
23110 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
23120 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
23130 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
23140 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
23150 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
23160 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
23170 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
23180 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23190 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
231a0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
231b0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
231c0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
231d0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
231e0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
231f0 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
23200 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
23210 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
23220 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
23230 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
23240 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
23250 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
23260 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
23270 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
23280 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
23290 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
232a0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
232b0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
232c0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
232d0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
232e0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
232f0 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
23300 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
23310 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23320 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
23330 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
23340 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
23350 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
23360 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
23370 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
23380 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
23390 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
233a0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
233b0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
233c0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
233d0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
233e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
233f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
23400 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
23410 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
23420 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
23430 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
23440 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
23450 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
23460 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
23470 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
23480 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
23490 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
234a0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
234b0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
234c0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
234d0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
234e0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
234f0 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
23500 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
23510 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
23520 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
23530 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
23540 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
23550 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
23560 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
23570 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
23580 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
23590 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
235a0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
235b0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
235c0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
235d0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
235e0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
235f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
23600 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
23610 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
23620 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
23630 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
23640 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
23650 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
23660 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
23670 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
23680 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
23690 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
236a0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
236b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
236c0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
236d0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
236e0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
236f0 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
23700 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
23710 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
23720 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
23730 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
23740 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
23750 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
23760 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
23770 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
23780 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
23790 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
237a0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
237b0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
237c0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
237d0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
237e0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
237f0 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
23800 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
23810 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
23820 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
23830 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
23840 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
23850 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
23860 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
23870 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
23880 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
23890 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
238a0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
238b0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
238c0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
238d0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
238e0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
238f0 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
23900 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
23910 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
23920 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
23930 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
23940 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
23950 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
23960 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
23970 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
23980 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
23990 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
239a0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
239b0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
239c0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
239d0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
239e0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
239f0 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
23a00 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
23a10 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
23a20 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
23a30 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
23a40 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
23a50 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
23a60 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
23a70 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
23a80 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
23a90 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
23aa0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
23ab0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
23ac0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
23ad0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
23ae0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
23af0 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
23b00 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
23b10 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
23b20 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
23b30 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
23b40 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
23b50 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
23b60 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
23b70 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
23b80 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
23b90 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
23ba0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
23bb0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
23bc0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
23bd0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
23be0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23bf0 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
23c00 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
23c10 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
23c20 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
23c30 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
23c40 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
23c50 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
23c60 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
23c70 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
23c80 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
23c90 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
23ca0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
23cb0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
23cc0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
23cd0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
23ce0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
23cf0 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
23d00 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
23d10 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
23d20 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
23d30 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
23d40 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
23d50 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
23d60 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
23d70 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
23d80 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
23d90 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
23da0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
23db0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
23dc0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
23dd0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
23de0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
23df0 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
23e00 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
23e10 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
23e20 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
23e30 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
23e40 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
23e50 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
23e60 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
23e70 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
23e80 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
23e90 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
23ea0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
23eb0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
23ec0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
23ed0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
23ee0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
23ef0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
23f00 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
23f10 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
23f20 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
23f30 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
23f40 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
23f50 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
23f60 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
23f70 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
23f80 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
23f90 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
23fa0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23fb0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
23fc0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
23fd0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
23fe0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
23ff0 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
24000 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
24010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
24020 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
24030 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
24040 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
24050 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
24060 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
24070 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
24080 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
24090 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
240a0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
240b0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
240c0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
240d0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
240e0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
240f0 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
24100 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
24110 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
24120 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
24130 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
24140 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
24150 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
24160 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
24170 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
24180 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
24190 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
241a0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
241b0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
241c0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
241d0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
241e0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
241f0 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
24200 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
24210 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
24220 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
24230 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
24240 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
24250 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
24260 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
24270 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
24280 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
24290 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
242a0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
242b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
242c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
242d0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
242e0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
242f0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
24300 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24310 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
24320 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
24330 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
24340 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
24350 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
24360 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
24370 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
24380 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
24390 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
243a0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
243b0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
243c0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
243d0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
243e0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
243f0 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
24400 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
24410 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
24420 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
24430 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
24440 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
24450 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
24460 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
24470 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
24480 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
24490 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
244a0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
244b0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
244c0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
244d0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
244e0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
244f0 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
24500 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
24510 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
24520 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
24530 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
24540 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
24550 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
24560 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
24570 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
24580 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
24590 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
245a0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
245b0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
245c0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
245d0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
245e0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
245f0 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
24600 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
24610 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
24620 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
24630 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
24640 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
24650 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
24660 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
24670 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
24680 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
24690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
246a0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
246b0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
246c0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
246d0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
246e0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
246f0 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
24700 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
24710 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
24720 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
24730 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
24740 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
24750 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
24760 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
24770 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
24780 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
24790 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
247a0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
247b0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
247c0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
247d0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
247e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
247f0 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
24800 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
24810 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
24820 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
24830 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
24840 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
24850 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
24860 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
24870 72 79 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ry].*/.int sqlit
24880 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
24890 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
248a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
248b0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
248c0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
248d0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
248e0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
248f0 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20  andle */.);.int 
24900 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
24910 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
24920 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
24930 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
24940 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
24950 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
24960 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
24970 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
24980 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
24990 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
249a0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
249b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
249c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
249d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
249e0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
249f0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
24a00 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
24a10 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
24a20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
24a30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
24a40 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
24a50 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
24a60 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
24a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
24a80 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
24a90 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
24aa0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
24ab0 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
24ac0 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
24ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
24ae0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
24af0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
24b00 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
24b10 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
24b20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
24b30 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
24b40 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
24b50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
24b60 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
24b70 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
24b80 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
24b90 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
24ba0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
24bb0 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
24bc0 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
24bd0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
24be0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
24bf0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
24c00 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
24c10 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
24c20 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
24c30 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
24c40 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
24c50 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
24c60 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
24c70 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
24c80 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
24c90 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
24ca0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
24cb0 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
24cc0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
24cd0 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
24ce0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
24cf0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
24d00 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
24d10 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
24d20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
24d30 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
24d40 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
24d50 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
24d60 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
24d70 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
24d80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
24d90 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
24da0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
24db0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24dc0 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
24dd0 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
24de0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
24df0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
24e00 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
24e10 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
24e20 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
24e30 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
24e40 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
24e50 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
24e60 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
24e70 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
24e80 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24e90 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
24ea0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
24eb0 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
24ec0 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
24ed0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
24ee0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
24ef0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
24f00 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
24f10 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
24f20 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
24f30 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
24f40 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
24f50 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
24f60 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
24f70 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
24f80 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
24f90 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
24fa0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
24fb0 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
24fc0 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
24fd0 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
24fe0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24ff0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
25000 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
25010 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
25020 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25030 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
25040 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
25050 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25060 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
25070 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
25080 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
25090 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
250a0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
250b0 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
250c0 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
250d0 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
250e0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
250f0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
25100 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
25110 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
25120 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
25130 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
25140 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
25150 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
25160 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
25170 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
25180 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25190 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
251a0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
251b0 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
251c0 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
251d0 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
251e0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
251f0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
25200 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
25210 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
25220 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
25230 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
25240 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
25250 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
25260 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
25270 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
25280 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
25290 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
252a0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
252b0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
252c0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  );.int sqlite3_u
252d0 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
252e0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
252f0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
25300 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
25310 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
25320 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
25330 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
25340 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
25350 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
25360 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
25370 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
25380 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  sages.** METHOD:
25390 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
253a0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
253b0 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  nt sqlite3_* API
253c0 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64   call associated
253d0 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62   with .** [datab
253e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
253f0 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74  D failed, then t
25400 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
25410 64 65 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a  de(D) interface.
25420 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ** returns the n
25430 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
25440 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  ode] or [extende
25450 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66  d result code] f
25460 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63  or that.** API c
25470 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d  all..** If the m
25480 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63  ost recent API c
25490 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73 73 66  all was successf
254a0 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ul,.** then the 
254b0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
254c0 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  m sqlite3_errcod
254d0 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
254e0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
254f0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
25500 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
25510 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
25520 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
25530 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
25540 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
25550 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
25560 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
25570 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
25580 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
25590 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
255a0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
255b0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
255c0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
255d0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
255e0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
255f0 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
25600 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
25610 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
25620 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
25630 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
25640 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
25650 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
25660 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
25670 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
25680 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
25690 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
256a0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
256b0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
256c0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
256d0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
256e0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
256f0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
25700 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
25710 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
25720 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  ions.)^.**.** ^T
25730 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74  he sqlite3_errst
25740 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  r() interface re
25750 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73  turns the Englis
25760 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a  h-language text.
25770 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69 62 65  ** that describe
25780 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f  s the [result co
25790 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a  de], as UTF-8..*
257a0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
257b0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
257c0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
257d0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
257e0 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f  y.** and must no
257f0 74 20 62 65 20 66 72 65 65 64 20 62 79 20 74 68  t be freed by th
25800 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e  e application)^.
25810 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
25820 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
25830 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69  ading mode] is i
25840 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20  n use, it might 
25850 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74  be the.** case t
25860 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72  hat a second err
25870 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73  or occurs on a s
25880 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 69  eparate thread i
25890 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  n between.** the
258a0 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72   time of the fir
258b0 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65  st error and the
258c0 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69   call to these i
258d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68  nterfaces..** Wh
258e0 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c  en that happens,
258f0 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f   the second erro
25900 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74  r will be report
25910 65 64 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a  ed since these.*
25920 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77  * interfaces alw
25930 61 79 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d  ays report the m
25940 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c  ost recent resul
25950 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20  t.  To avoid.** 
25960 74 68 69 73 2c 20 65 61 63 68 20 74 68 72 65 61  this, each threa
25970 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63  d can obtain exc
25980 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20 74 68  lusive use of th
25990 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
259a0 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20  ection] D.** by 
259b0 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
259c0 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b  3_mutex_enter]([
259d0 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
259e0 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62 65 67  ](D)) before beg
259f0 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65  inning.** to use
25a00 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20   D and invoking 
25a10 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c  [sqlite3_mutex_l
25a20 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64  eave]([sqlite3_d
25a30 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74  b_mutex](D)) aft
25a40 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20  er.** all calls 
25a50 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  to the interface
25a60 73 20 6c 69 73 74 65 64 20 68 65 72 65 20 61 72  s listed here ar
25a70 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a  e completed..**.
25a80 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61  ** If an interfa
25a90 63 65 20 66 61 69 6c 73 20 77 69 74 68 20 53 51  ce fails with SQ
25aa0 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61  LITE_MISUSE, tha
25ab0 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65  t means the inte
25ac0 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76  rface.** was inv
25ad0 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  oked incorrectly
25ae0 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
25af0 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61  ion.  In that ca
25b00 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72  se, the.** error
25b10 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67   code and messag
25b20 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74  e may or may not
25b30 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20   be set..*/.int 
25b40 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
25b50 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e  sqlite3 *db);.in
25b60 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
25b70 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
25b80 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63  e3 *db);.const c
25b90 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  har *sqlite3_err
25ba0 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  msg(sqlite3*);.c
25bb0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
25bc0 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69  e3_errmsg16(sqli
25bd0 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61  te3*);.const cha
25be0 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74  r *sqlite3_errst
25bf0 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  r(int);../*.** C
25c00 41 50 49 33 52 45 46 3a 20 50 72 65 70 61 72 65  API3REF: Prepare
25c10 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
25c20 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
25c30 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
25c40 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
25c50 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
25c60 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
25c70 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
25c80 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
25c90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
25ca0 61 74 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63  at.** has been c
25cb0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e  ompiled into bin
25cc0 61 72 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20  ary form and is 
25cd0 72 65 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c  ready to be eval
25ce0 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  uated..**.** Thi
25cf0 6e 6b 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73  nk of each SQL s
25d00 74 61 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65  tatement as a se
25d10 70 61 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20  parate computer 
25d20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a  program.  The.**
25d30 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
25d40 78 74 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64  xt is source cod
25d50 65 2e 20 20 41 20 70 72 65 70 61 72 65 64 20 73  e.  A prepared s
25d60 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
25d70 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69  .** is the compi
25d80 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e  led object code.
25d90 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62    All SQL must b
25da0 65 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  e converted into
25db0 20 61 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73   a.** prepared s
25dc0 74 61 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20  tatement before 
25dd0 69 74 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a  it can be run..*
25de0 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79  *.** The life-cy
25df0 63 6c 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  cle of a prepare
25e00 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
25e10 63 74 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20  ct usually goes 
25e20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
25e30 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
25e40 65 61 74 65 20 74 68 65 20 70 72 65 70 61 72 65  eate the prepare
25e50 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
25e60 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
25e70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e  3_prepare_v2()].
25e80 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
25e90 6c 75 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74  lues to [paramet
25ea0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
25eb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
25ec0 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
25ed0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
25ee0 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
25ef0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
25f00 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
25f10 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
25f20 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
25f30 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
25f40 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
25f50 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
25f60 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
25f70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
25f80 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
25f90 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
25fa0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
25fb0 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
25fc0 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
25fd0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
25fe0 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
25ff0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
26000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
26010 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
26020 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
26030 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  3.**.** ^(This i
26040 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
26050 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
26060 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
26070 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
26080 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
26090 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
260a0 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
260b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
260c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
260d0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
260e0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
260f0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
26100 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
26110 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
26120 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
26130 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
26140 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
26150 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
26160 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
26170 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
26180 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
26190 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
261a0 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
261b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
261c0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
261d0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
261e0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
261f0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
26200 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
26210 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
26220 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
26230 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
26240 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
26250 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
26260 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
26270 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
26280 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
26290 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
262a0 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
262b0 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
262c0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
262d0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
262e0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
262f0 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
26300 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
26310 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
26320 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
26330 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
26340 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
26350 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
26360 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
26370 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26380 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
26390 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
263a0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
263b0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
263c0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
263d0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
263e0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
263f0 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
26400 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
26410 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
26420 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
26430 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
26440 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
26450 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
26460 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
26470 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
26480 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
26490 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
264a0 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
264b0 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
264c0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
264d0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
264e0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
264f0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
26500 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
26510 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
26520 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
26530 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
26540 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
26550 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
26560 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
26570 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
26580 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
26590 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
265a0 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
265b0 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
265c0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
265d0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
265e0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
265f0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
26600 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
26610 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
26620 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
26630 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
26640 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
26650 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
26660 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
26670 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
26680 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
26690 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
266a0 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
266b0 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
266c0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
266d0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
266e0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
266f0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
26700 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
26710 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
26720 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
26730 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
26740 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
26750 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
26760 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
26770 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
26780 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
26790 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
267a0 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
267b0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
267c0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
267d0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
267e0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
267f0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
26800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26810 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
26820 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
26830 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
26840 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
26850 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
26860 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
26870 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
26880 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
26890 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
268a0 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
268b0 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
268c0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
268d0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
268e0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
268f0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
26900 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
26910 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
26920 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
26930 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
26940 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
26950 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
26960 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
26970 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
26980 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26990 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
269a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
269b0 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
269c0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
269d0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
269e0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
269f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26a00 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
26a10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26a20 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
26a30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26a40 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26a50 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
26a60 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
26a70 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
26a80 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
26a90 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26aa0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
26ab0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ac0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
26ad0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
26ae0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
26af0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
26b00 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
26b10 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
26b20 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26b30 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
26b40 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
26b50 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
26b60 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
26b70 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26b80 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
26b90 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26ba0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
26bb0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26bc0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
26bd0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
26be0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
26bf0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
26c00 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
26c10 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
26c20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26c30 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
26c40 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
26c50 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
26c60 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
26c70 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
26c80 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
26c90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26ca0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
26cb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
26cc0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
26cd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26ce0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
26cf0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
26d00 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
26d10 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
26d20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
26d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
26d40 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
26d50 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
26d60 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
26d70 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
26d80 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
26d90 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
26da0 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
26db0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
26dc0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
26dd0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
26de0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
26df0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
26e00 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
26e10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
26e20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
26e30 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
26e40 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
26e50 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
26e60 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
26e70 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
26e80 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
26e90 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
26ea0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
26eb0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
26ec0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
26ed0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
26ee0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
26ef0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26f00 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
26f10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
26f20 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26f30 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
26f40 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
26f50 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
26f60 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
26f70 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
26f80 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
26f90 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
26fa0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26fb0 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
26fc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26fd0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
26fe0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
26ff0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
27000 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
27010 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
27020 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
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 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27050 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
27060 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
27070 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
27080 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
27090 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
270a0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
270b0 5f 54 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74  _THREADS]] ^(<dt
270c0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  >SQLITE_LIMIT_WO
270d0 52 4b 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74  RKER_THREADS</dt
270e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
270f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
27100 75 78 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20  uxiliary worker 
27110 74 68 72 65 61 64 73 20 74 68 61 74 20 61 20 73  threads that a s
27120 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72  ingle.** [prepar
27130 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61  ed statement] ma
27140 79 20 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a  y start.</dd>)^.
27150 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
27160 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27170 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
27180 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
27190 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
271a0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
271b0 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
271c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
271d0 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
271e0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
271f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
27200 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
27210 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
27220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
27230 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
27240 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
27250 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27260 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
27270 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27280 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
27290 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
272a0 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
272b0 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
272c0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
272d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
272e0 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
272f0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
27300 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
27310 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
27320 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27330 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
27340 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
27350 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
27360 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
27370 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
27380 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
27390 45 52 5f 54 48 52 45 41 44 53 20 20 20 20 20 20  ER_THREADS      
273a0 20 20 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43       11../*.** C
273b0 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
273c0 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
273d0 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
273e0 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
273f0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54  compiler}.** MET
27400 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20  HOD: sqlite3.** 
27410 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c  CONSTRUCTOR: sql
27420 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
27430 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
27440 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
27450 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
27460 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
27470 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
27480 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
27490 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
274a0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
274b0 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
274c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
274d0 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
274e0 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
274f0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
27500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
27510 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
27520 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
27530 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
27540 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
27550 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
27560 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
27570 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
27580 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
27590 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
275a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
275b0 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
275c0 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
275d0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
275e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
275f0 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
27600 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27610 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
27620 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
27630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27640 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
27650 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
27660 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
27670 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
27680 61 72 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61  argument is nega
27690 74 69 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20  tive, then zSql 
276a0 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74 68  is read up to th
276b0 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20  e.** first zero 
276c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20  terminator. ^If 
276d0 6e 42 79 74 65 20 69 73 20 70 6f 73 69 74 69 76  nByte is positiv
276e0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
276f0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
27700 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
27710 53 71 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20  Sql.  ^If nByte 
27720 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f  is zero, then no
27730 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
27740 74 65 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61  tement is genera
27750 74 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63  ted..** If the c
27760 61 6c 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74  aller knows that
27770 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
27780 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
27790 69 6e 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  inated, then.** 
277a0 74 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c  there is a small
277b0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
277c0 61 6e 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e  antage to passin
277d0 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d  g an nByte param
277e0 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20  eter that.** is 
277f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27800 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
27810 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
27820 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
27830 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a  nul-terminator..
27840 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
27850 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
27860 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
27870 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
27880 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
27890 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
278a0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
278b0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
278c0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
278d0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
278e0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
278f0 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
27900 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
27910 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
27920 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
27930 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
27940 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
27950 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
27960 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
27970 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
27980 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
27990 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
279a0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
279b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
279c0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
279d0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
279e0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
279f0 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
27a00 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
27a10 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
27a20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
27a30 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
27a40 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
27a50 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
27a60 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
27a70 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
27a80 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
27a90 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
27aa0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
27ab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
27ac0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
27ad0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
27ae0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
27af0 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
27b00 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
27b10 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27b20 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
27b30 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
27b40 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
27b50 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
27b60 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
27b70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
27b80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27b90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27ba0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
27bb0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
27bc0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
27bd0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
27be0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
27bf0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
27c00 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
27c10 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
27c20 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
27c30 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
27c40 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
27c50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
27c60 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
27c70 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
27c80 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
27c90 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
27ca0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
27cb0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
27cc0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
27cd0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
27ce0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
27cf0 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
27d00 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
27d10 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
27d20 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
27d30 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
27d40 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
27d50 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
27d60 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
27d70 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
27d80 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
27d90 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
27da0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27db0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
27dc0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
27dd0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
27de0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
27df0 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20  un it again. As 
27e00 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f  many as [SQLITE_
27e10 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59  MAX_SCHEMA_RETRY
27e20 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c  ].** retries wil
27e30 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73  l occur before s
27e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67 69  qlite3_step() gi
27e50 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75 72  ves up and retur
27e60 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20  ns an error..** 
27e70 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
27e80 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
27e90 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
27ea0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
27eb0 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
27ec0 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
27ed0 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
27ee0 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
27ef0 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
27f00 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
27f10 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
27f20 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
27f30 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
27f40 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
27f50 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
27f60 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
27f70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
27f80 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
27f90 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
27fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
27fb0 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
27fc0 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
27fd0 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
27fe0 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
27ff0 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
28000 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
28010 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
28020 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
28030 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
28040 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
28050 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
28060 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
28070 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
28080 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
28090 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
280a0 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
280b0 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
280c0 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
280d0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
280e0 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
280f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
28100 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
28110 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
28120 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
28130 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
28140 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
28150 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
28160 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
28170 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
28180 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
28190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
281a0 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
281b0 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
281c0 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
281d0 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
281e0 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
281f0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
28200 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
28210 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
28220 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
28230 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
28240 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
28250 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
28260 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
28270 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
28280 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
28290 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
282a0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
282b0 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
282c0 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
282d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
282e0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69  enabled..** </li
282f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e  >.** </ol>.*/.in
28300 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
28310 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
28320 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28330 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28340 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28350 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28360 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28370 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
28380 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
28390 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
283a0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
283b0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
283c0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
283d0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
283e0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
283f0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
28400 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
28410 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
28420 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
28430 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
28440 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65  .int sqlite3_pre
28450 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
28460 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
28470 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
28480 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28490 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
284a0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
284b0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
284c0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
284d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
284e0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
284f0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
28500 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
28510 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
28520 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
28530 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
28540 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
28550 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
28560 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
28570 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
28580 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
28590 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20  e3_prepare16(.  
285a0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
285b0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
285c0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
285d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
285e0 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
285f0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
28600 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28610 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28620 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28630 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28640 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28650 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28660 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28670 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28680 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28690 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
286a0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
286b0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
286c0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
286d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
286e0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
286f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
28700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
28710 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
28720 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
28730 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
28740 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
28750 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28760 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28770 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28780 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
28790 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
287a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
287b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
287c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
287d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
287e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
287f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
28800 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
28810 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
28820 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
28830 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
28840 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28850 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28860 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
28870 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
28880 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
28890 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
288a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
288b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
288c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
288d0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
288e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
288f0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
28900 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
28910 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
28920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28930 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  _v2()]..*/.const
28940 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
28950 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
28960 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28970 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
28980 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
28990 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
289a0 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
289b0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
289c0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
289d0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
289e0 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
289f0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28a00 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
28a10 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
28a20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28a30 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
28a40 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
28a50 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
28a60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
28a70 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
28a80 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
28a90 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28aa0 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
28ab0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
28ac0 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
28ad0 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
28ae0 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
28af0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
28b00 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
28b10 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
28b20 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
28b30 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
28b40 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
28b50 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
28b60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
28b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
28b80 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
28b90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
28ba0 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
28bb0 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
28bc0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
28bd0 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
28be0 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
28bf0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
28c00 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
28c10 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
28c20 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
28c30 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
28c40 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
28c50 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
28c60 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
28c70 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28c80 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
28c90 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
28ca0 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
28cb0 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
28cc0 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
28cd0 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
28ce0 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
28cf0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
28d00 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
28d10 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
28d20 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
28d30 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
28d40 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
28d50 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
28d60 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
28d70 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
28d80 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
28d90 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
28da0 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
28db0 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
28dc0 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
28dd0 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
28de0 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
28df0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
28e00 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
28e10 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28e20 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
28e30 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
28e40 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
28e50 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
28e60 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
28e70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
28e80 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
28e90 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
28ea0 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
28eb0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
28ec0 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
28ed0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  /.int sqlite3_st
28ee0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
28ef0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
28f00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28f10 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
28f20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
28f30 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
28f40 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
28f50 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
28f60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
28f70 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
28f80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
28f90 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
28fa0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
28fb0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
28fc0 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
28fd0 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
28fe0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
28ff0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
29000 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
29010 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
29020 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
29030 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
29040 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
29050 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
29060 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
29070 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
29080 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29090 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
290a0 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
290b0 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
290c0 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
290d0 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
290e0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
290f0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
29100 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
29110 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
29120 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
29130 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
29140 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
29150 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
29160 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
29170 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
29180 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
29190 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
291a0 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
291b0 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
291c0 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
291d0 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
291e0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
291f0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
29200 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
29210 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
29220 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
29230 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
29240 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
29250 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
29260 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
29270 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
29280 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
29290 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
292a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
292b0 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
292c0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
292d0 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
292e0 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
292f0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
29300 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
29310 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
29320 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29330 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
29340 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
29350 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29360 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
29370 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
29380 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
29390 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
293a0 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
293b0 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
293c0 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
293d0 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
293e0 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
293f0 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
29400 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
29410 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
29420 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
29430 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
29440 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
29450 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
29460 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
29470 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
29480 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
29490 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
294a0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
294b0 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
294c0 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
294d0 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
294e0 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
294f0 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
29500 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
29510 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
29520 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
29530 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
29540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
29550 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
29560 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
29570 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
29580 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
29590 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
295a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
295b0 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
295c0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
295d0 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
295e0 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
295f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
29600 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
29610 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
29630 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
29640 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
29650 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
29660 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
29670 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
29680 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
29690 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
296a0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
296b0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
296c0 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
296d0 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
296e0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
296f0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
29700 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
29710 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
29720 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
29730 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
29740 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
29750 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
29760 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
29770 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
29780 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
29790 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
297a0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
297b0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
297c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
297d0 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
297e0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
297f0 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
29800 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
29810 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
29820 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
29830 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29840 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
29850 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
29860 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
29870 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
29880 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
29890 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
298a0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
298b0 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
298c0 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
298d0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
298e0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
298f0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29900 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29910 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
29920 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
29930 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
29940 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
29950 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
29960 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
29970 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
29980 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
29990 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
299a0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
299b0 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
299c0 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
299d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
299e0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
299f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29a00 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
29a10 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
29a20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29a30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29a40 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
29a50 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
29a60 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
29a70 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29a80 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
29a90 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
29aa0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
29ab0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
29ac0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
29ad0 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
29ae0 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
29af0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29b00 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
29b10 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
29b20 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
29b30 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
29b40 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
29b50 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
29b60 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
29b70 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
29b80 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
29b90 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
29ba0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
29bb0 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
29bc0 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
29bd0 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
29be0 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
29bf0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
29c00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29c10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
29c20 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
29c30 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29c40 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
29c50 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
29c60 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
29c70 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
29c80 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
29c90 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
29ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
29cb0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
29cc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
29cd0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
29ce0 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
29cf0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
29d00 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
29d10 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
29d20 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
29d30 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
29d40 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
29d50 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
29d60 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
29d70 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
29d80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
29d90 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
29da0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29db0 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
29dc0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
29dd0 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
29de0 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
29df0 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
29e00 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
29e10 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
29e20 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
29e30 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
29e40 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
29e50 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
29e60 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
29e70 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
29e80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
29e90 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
29ea0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
29eb0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
29ec0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
29ed0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
29ee0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
29ef0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
29f00 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
29f10 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
29f20 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
29f30 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
29f40 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
29f50 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
29f60 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
29f70 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
29f80 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
29f90 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
29fa0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
29fb0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
29fc0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
29fd0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
29fe0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
29ff0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2a000 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2a010 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2a020 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2a030 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2a040 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2a050 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2a060 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2a070 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2a080 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2a090 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2a0a0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2a0b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2a0c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2a0d0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2a0e0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2a0f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2a100 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2a110 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2a120 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2a130 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2a140 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2a150 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2a160 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2a170 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2a180 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2a190 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2a1a0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2a1b0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2a1c0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2a1d0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2a1e0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2a1f0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2a200 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2a210 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2a220 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2a230 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2a240 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2a250 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2a260 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2a270 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2a280 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2a290 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2a2a0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2a2b0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2a2c0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2a2d0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2a2e0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2a2f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2a300 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2a310 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2a320 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2a330 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2a340 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2a350 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2a360 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2a370 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2a380 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2a390 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2a3a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2a3b0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2a3c0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2a3d0 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2a3e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2a3f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2a400 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2a410 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2a420 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2a430 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2a440 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2a450 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2a460 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2a470 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2a480 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2a490 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2a4a0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2a4b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2a4c0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2a4d0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2a4e0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2a4f0 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2a500 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2a510 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2a520 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2a530 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2a540 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2a550 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a560 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2a570 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2a580 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2a590 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2a5a0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2a5b0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2a5c0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2a5d0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2a5e0 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2a5f0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2a600 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2a610 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2a620 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2a630 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2a640 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2a650 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2a660 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2a670 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2a680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2a690 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2a6a0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2a6b0 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2a6c0 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2a6d0 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2a6e0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2a6f0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2a700 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2a710 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2a720 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2a730 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2a740 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2a750 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2a760 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2a770 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2a780 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2a790 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2a7a0 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2a7b0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2a7c0 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2a7d0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2a7e0 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2a7f0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2a800 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2a810 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2a820 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2a830 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2a840 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2a850 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2a860 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2a870 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2a880 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2a890 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2a8a0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2a8b0 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2a8c0 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2a8d0 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2a8e0 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2a8f0 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2a900 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2a910 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2a920 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2a930 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2a940 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2a950 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2a960 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2a970 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2a980 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2a990 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2a9a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2a9b0 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2a9c0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2a9d0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2a9e0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2a9f0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2aa00 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2aa10 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2aa20 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2aa30 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2aa40 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2aa50 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2aa60 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2aa70 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2aa80 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2aa90 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2aaa0 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2aab0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2aac0 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2aad0 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2aae0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2aaf0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2ab00 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2ab10 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2ab20 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2ab30 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2ab40 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2ab50 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2ab60 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2ab70 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2ab80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ab90 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2aba0 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2abb0 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2abc0 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2abd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2abe0 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2abf0 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2ac00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2ac10 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2ac20 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2ac30 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2ac40 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2ac50 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2ac60 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2ac70 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2ac80 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2ac90 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2aca0 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2acb0 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2acc0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2acd0 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2ace0 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2acf0 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2ad00 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2ad10 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2ad20 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2ad30 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2ad40 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2ad50 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2ad60 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2ad70 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2ad80 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2ad90 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2ada0 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2adb0 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2adc0 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2add0 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2ade0 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2adf0 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2ae00 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2ae10 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2ae20 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2ae30 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2ae40 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2ae50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ae60 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2ae70 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae80 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2ae90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2aea0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2aeb0 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2aec0 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2aed0 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2aee0 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2aef0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2af00 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2af10 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2af20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2af30 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2af40 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2af50 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2af60 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2af70 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2af80 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2af90 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2afa0 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2afb0 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2afc0 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2afd0 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2afe0 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2aff0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2b000 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2b010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2b020 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2b030 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2b040 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2b050 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2b060 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2b070 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2b080 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
2b090 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
2b0a0 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
2b0b0 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
2b0c0 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
2b0d0 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
2b0e0 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
2b0f0 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
2b100 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
2b110 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
2b120 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2b130 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2b140 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2b150 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2b160 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2b170 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2b180 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2b190 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2b1a0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b1b0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2b1c0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b1d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b1e0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2b1f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2b200 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2b210 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
2b220 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2b230 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2b240 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2b250 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b260 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b270 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  d_blob64(sqlite3
2b280 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b290 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65  st void*, sqlite
2b2a0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2b2b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b2c0 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29    void(*)(void*)
2b2d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2b2e0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2b2f0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
2b300 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69  ouble);.int sqli
2b310 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c  te3_bind_int(sql
2b320 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b330 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
2b340 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71  e3_bind_int64(sq
2b350 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b360 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
2b370 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b380 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2b390 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74  stmt*, int);.int
2b3a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2b3b0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2b3c0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
2b3d0 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69  ,int,void(*)(voi
2b3e0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2b3f0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2b400 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b410 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2b420 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2b430 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
2b440 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c  _bind_text64(sql
2b450 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2b460 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2b470 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20  lite3_uint64,.  
2b480 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b490 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2b4a0 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20  oid*), unsigned 
2b4b0 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a  char encoding);.
2b4c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2b4d0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2b4e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2b4f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2b500 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b510 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  nd_zeroblob(sqli
2b520 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2b530 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73 71 6c 69  int n);.int sqli
2b540 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2b550 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
2b560 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
2b570 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
2b580 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2b590 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2b5a0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
2b5b0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2b5c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
2b5d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
2b5e0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
2b5f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
2b600 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
2b610 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2b620 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
2b630 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
2b640 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
2b650 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
2b660 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
2b670 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
2b680 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
2b690 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
2b6a0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
2b6b0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
2b6c0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
2b6d0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
2b6e0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
2b6f0 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
2b700 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
2b710 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
2b720 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
2b730 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
2b740 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
2b750 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
2b760 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
2b770 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
2b780 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
2b790 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
2b7a0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
2b7b0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
2b7c0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
2b7d0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
2b7e0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
2b7f0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2b800 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2b810 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2b820 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b830 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
2b840 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2b850 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2b860 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
2b870 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b880 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  r_count(sqlite3_
2b890 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2b8a0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
2b8b0 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65   A Host Paramete
2b8c0 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  r.** METHOD: sql
2b8d0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2b8e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2b8f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2b900 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2b910 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2b920 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2b930 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2b940 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2b950 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2b960 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2b970 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2b980 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2b990 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2b9a0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2b9b0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2b9c0 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2b9d0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2b9e0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2b9f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2ba00 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2ba10 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2ba20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2ba30 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2ba40 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2ba50 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2ba60 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2ba70 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2ba80 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2ba90 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2baa0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2bab0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2bac0 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2bad0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2bae0 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2baf0 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2bb00 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2bb10 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2bb20 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2bb30 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2bb40 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2bb50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2bb60 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2bb70 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2bb80 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2bb90 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2bba0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2bbb0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2bbc0 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2bbd0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2bbe0 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2bbf0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2bc00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2bc10 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2bc20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2bc30 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2bc40 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2bc50 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2bc60 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2bc70 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2bc80 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2bc90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2bca0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bcb0 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ()]..*/.const ch
2bcc0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2bcd0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2bce0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2bcf0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2bd00 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2bd10 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2bd20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20  A Given Name.** 
2bd30 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2bd40 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2bd50 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2bd60 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2bd70 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2bd80 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2bd90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2bda0 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2bdb0 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2bdc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2bdd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bde0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2bdf0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2be00 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2be10 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2be20 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2be30 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2be40 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2be50 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2be60 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2be70 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2be80 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2be90 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2bea0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2beb0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2bec0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2bed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bee0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bef0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2bf00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bf10 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2bf20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bf30 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a  ameter_name()]..
2bf40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2bf50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2bf60 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2bf70 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2bf80 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2bf90 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2bfa0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2bfb0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2bfc0 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2bfd0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2bfe0 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2bff0 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2c000 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2c010 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2c020 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2c030 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2c040 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2c050 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2c060 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2c070 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2c080 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2c090 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2c0a0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2c0b0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2c0c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2c0d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c0e0 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
2c0f0 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
2c100 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
2c110 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2c120 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2c130 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2c140 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2c150 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c160 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2c170 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2c180 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c190 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2c1a0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2c1b0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2c1c0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2c1d0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2c1e0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2c1f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2c200 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2c210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2c220 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2c230 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2c240 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c250 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2c260 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2c270 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2c280 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2c290 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2c2a0 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
2c2b0 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
2c2c0 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
2c2d0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2c2e0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
2c2f0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
2c300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c310 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
2c320 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2c330 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2c340 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
2c350 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
2c360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c370 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
2c380 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2c390 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
2c3a0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2c3b0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
2c3c0 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
2c3d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c3e0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
2c3f0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
2c400 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
2c410 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2c420 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
2c430 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
2c440 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2c450 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
2c460 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2c470 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
2c480 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
2c490 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
2c4a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2c4b0 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
2c4c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
2c4d0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2c4e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2c4f0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2c500 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2c510 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2c520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2c530 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2c540 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2c550 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
2c560 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
2c570 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
2c580 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2c590 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
2c5a0 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
2c5b0 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
2c5c0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
2c5d0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
2c5e0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
2c5f0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
2c600 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
2c610 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
2c620 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
2c630 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
2c640 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
2c650 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2c660 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
2c670 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
2c680 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
2c690 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
2c6a0 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
2c6b0 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
2c6c0 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
2c6d0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
2c6e0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
2c6f0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
2c700 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
2c710 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
2c720 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
2c730 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
2c740 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74  e next..*/.const
2c750 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2c760 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  olumn_name(sqlit
2c770 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29  e3_stmt*, int N)
2c780 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c790 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c7a0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c7b0 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2c7c0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2c7d0 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2c7e0 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
2c7f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2c800 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
2c810 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2c820 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2c830 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2c840 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2c850 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2c860 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2c870 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2c880 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2c890 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2c8a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2c8b0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2c8c0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2c8d0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2c8e0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2c8f0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2c900 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2c910 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2c920 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2c930 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2c940 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2c950 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2c960 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2c970 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2c980 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2c990 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2c9a0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2c9b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2c9c0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2c9d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c9e0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2c9f0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2ca00 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2ca10 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2ca20 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2ca30 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2ca40 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2ca50 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2ca60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ca70 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2ca80 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2ca90 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2caa0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2cab0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2cac0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2cad0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2cae0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2caf0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2cb00 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2cb10 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2cb20 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2cb30 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2cb40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2cb50 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2cb60 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2cb70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cb80 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2cb90 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2cba0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2cbb0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2cbc0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2cbd0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2cbe0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2cbf0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2cc00 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2cc10 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2cc20 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2cc30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2cc40 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2cc50 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2cc60 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2cc70 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2cc80 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2cc90 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2cca0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2ccb0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2ccc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2ccd0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2cce0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2ccf0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2cd00 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2cd10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2cd20 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2cd30 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2cd40 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2cd50 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2cd60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2cd70 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2cd80 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2cd90 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2cda0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2cdb0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2cdc0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2cdd0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2cde0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2cdf0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2ce00 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2ce10 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2ce20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2ce30 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2ce40 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2ce50 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2ce60 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2ce70 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2ce80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2ce90 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2cea0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2ceb0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2cec0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2ced0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2cee0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2cef0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2cf00 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2cf10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cf20 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2cf30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2cf40 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2cf50 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2cf60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2cf70 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2cf80 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2cf90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2cfa0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2cfb0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2cfc0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2cfd0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2cfe0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cff0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2d000 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2d010 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2d020 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2d030 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2d040 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2d050 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2d060 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d070 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2d080 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2d090 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2d0a0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d0b0 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2d0c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2d0d0 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2d0e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d0f0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d100 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2d110 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2d120 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2d130 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2d140 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2d150 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d160 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2d170 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2d180 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2d190 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d1a0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2d1b0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2d1c0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2d1d0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d  uery Result.** M
2d1e0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2d1f0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  tmt.**.** ^(The 
2d200 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2d210 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2d220 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2d230 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2d240 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2d250 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2d260 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2d270 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2d280 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2d290 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2d2a0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2d2b0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2d2c0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2d2d0 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2d2e0 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2d2f0 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2d300 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2d310 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2d320 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2d330 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2d340 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2d350 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2d360 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2d370 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2d380 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2d390 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2d3a0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2d3b0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2d3c0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2d3d0 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2d3e0 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2d3f0 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2d400 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2d410 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2d420 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2d430 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2d440 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2d450 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2d460 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2d470 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2d480 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2d490 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2d4a0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2d4b0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2d4c0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2d4d0 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2d4e0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2d4f0 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2d500 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2d510 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2d520 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2d530 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2d540 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2d550 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2d560 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2d570 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2d580 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2d590 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2d5a0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2d5b0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2d5c0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2d5d0 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2d5e0 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2d5f0 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2d600 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2d610 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2d620 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2d630 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2d640 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63  ose values..*/.c
2d650 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2d660 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2d670 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2d680 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2d690 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2d6a0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2d6b0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d6c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d6d0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2d6e0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  L Statement.** M
2d6f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2d700 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  tmt.**.** After 
2d710 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d720 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2d730 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2d740 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2d750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d760 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d770 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2d780 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2d790 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2d7a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d7b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2d7c0 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2d7d0 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2d7e0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2d7f0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2d800 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2d810 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2d820 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2d830 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2d840 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2d850 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2d860 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2d870 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2d880 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2d890 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2d8a0 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2d8b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d8c0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2d8d0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d8e0 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2d8f0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2d900 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2d910 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2d920 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2d930 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2d940 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2d950 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2d960 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2d970 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2d980 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2d990 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2d9a0 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2d9b0 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2d9c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2d9d0 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2d9e0 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2d9f0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2da00 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2da10 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2da20 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2da30 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2da40 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2da50 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2da60 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2da70 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2da80 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2da90 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2daa0 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2dab0 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2dac0 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2dad0 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2dae0 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2daf0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2db00 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2db10 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2db20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2db30 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2db40 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2db50 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2db60 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2db70 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2db80 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2db90 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2dba0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2dbb0 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2dbc0 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2dbd0 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2dbe0 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2dbf0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2dc00 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2dc10 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2dc20 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2dc30 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2dc40 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2dc50 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2dc60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2dc70 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2dc80 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2dc90 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2dca0 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2dcb0 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2dcc0 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2dcd0 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2dce0 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2dcf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dd00 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2dd10 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2dd20 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2dd30 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2dd40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2dd50 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2dd60 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2dd70 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2dd80 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2dd90 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2dda0 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2ddb0 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2ddc0 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2ddd0 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2dde0 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2ddf0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2de00 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2de10 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2de20 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2de30 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2de40 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2de50 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2de60 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2de70 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2de80 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2de90 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2dea0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2deb0 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2dec0 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2ded0 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2dee0 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2def0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2df00 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2df10 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2df20 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2df30 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2df40 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2df50 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2df60 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2df70 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2df80 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2df90 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2dfa0 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2dfb0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2dfc0 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2dfd0 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2dfe0 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2dff0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e000 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2e010 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2e020 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2e030 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2e040 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2e050 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2e060 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2e070 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2e080 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2e090 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2e0a0 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2e0b0 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2e0c0 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2e0d0 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2e0e0 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2e0f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e100 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2e110 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2e120 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2e130 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2e140 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2e150 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2e160 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2e170 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2e180 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2e190 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2e1a0 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2e1b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e1c0 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2e1d0 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2e1e0 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2e1f0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2e200 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2e210 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2e220 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2e230 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2e240 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2e250 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2e260 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2e270 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2e280 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2e290 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2e2a0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2e2b0 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2e2c0 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2e2d0 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2e2e0 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2e2f0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2e300 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e310 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2e320 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e330 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2e340 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2e350 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2e360 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e370 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2e380 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2e390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2e3a0 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2e3b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e3c0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2e3d0 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2e3e0 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2e3f0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2e400 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2e410 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2e420 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2e430 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2e440 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2e450 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2e460 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2e470 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2e480 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2e490 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2e4a0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2e4b0 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2e4c0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2e4d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2e4e0 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2e4f0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2e500 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2e510 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2e520 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2e530 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2e540 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2e550 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2e560 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2e570 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2e580 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2e590 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2e5a0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e5b0 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2e5c0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2e5d0 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2e5e0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e5f0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2e600 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2e610 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2e620 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2e630 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2e640 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2e650 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2e660 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2e670 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2e680 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2e690 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2e6a0 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2e6b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e6c0 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2e6d0 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2e6e0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2e6f0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2e700 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e710 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e720 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2e730 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2e740 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2e750 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2e760 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e770 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2e780 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2e790 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2e7a0 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2e7b0 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2e7c0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2e7d0 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2e7e0 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2e7f0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2e800 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
2e810 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2e820 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2e830 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2e840 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2e850 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20  a result set.** 
2e860 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e870 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2e880 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2e890 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65 20  nt(P) interface 
2e8a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e8b0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2e8c0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
2e8d0 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c  row of the resul
2e8e0 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72  t set of [prepar
2e8f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
2e900 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64  .** ^If prepared
2e910 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65   statement P doe
2e920 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c  s not have resul
2e930 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74 75  ts ready to retu
2e940 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73  rn.** (via calls
2e950 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2e960 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71  _column_int | sq
2e970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29  lite3_column_*()
2e980 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  ] of.** interfac
2e990 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  es) then sqlite3
2e9a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2e9b0 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68  eturns 0..** ^Th
2e9c0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2e9d0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2e9e0 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69  also returns 0 i
2e9f0 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f P is a NULL po
2ea00 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73  inter..** ^The s
2ea10 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ea20 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74  t(P) routine ret
2ea30 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70 72  urns 0 if the pr
2ea40 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a  evious call to.*
2ea50 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  * [sqlite3_step]
2ea60 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51  (P) returned [SQ
2ea70 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68  LITE_DONE].  ^Th
2ea80 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ea90 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20  ount(P).** will 
2eaa0 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20  return non-zero 
2eab0 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  if previous call
2eac0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ead0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a  p](P) returned.*
2eae0 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  * [SQLITE_ROW], 
2eaf0 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63 61  except in the ca
2eb00 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d  se of the [PRAGM
2eb10 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61  A incremental_va
2eb20 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69  cuum].** where i
2eb30 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  t always returns
2eb40 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68   zero since each
2eb50 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75   step of that mu
2eb60 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67  lti-step.** prag
2eb70 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c  ma returns 0 col
2eb80 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a  umns of data..**
2eb90 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2eba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2ebb0 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71  unt()].*/.int sq
2ebc0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2ebd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2ebe0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2ebf0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
2ec00 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
2ec10 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
2ec20 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
2ec30 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
2ec40 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
2ec50 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
2ec60 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
2ec70 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
2ec80 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
2ec90 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
2eca0 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
2ecb0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
2ecc0 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
2ecd0 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
2ece0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
2ecf0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
2ed00 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
2ed10 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
2ed20 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
2ed30 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
2ed40 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
2ed50 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
2ed60 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
2ed70 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
2ed80 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
2ed90 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
2eda0 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
2edb0 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
2edc0 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
2edd0 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
2ede0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
2edf0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
2ee00 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
2ee10 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
2ee20 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
2ee30 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2ee40 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
2ee50 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
2ee60 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
2ee70 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
2ee80 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
2ee90 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
2eea0 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
2eeb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
2eec0 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
2eed0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
2eee0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
2eef0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
2ef00 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
2ef10 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
2ef20 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
2ef30 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
2ef40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ef50 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ef60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2ef70 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2ef80 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2ef90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2efa0 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2efb0 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2efc0 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2efd0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2efe0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2eff0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2f000 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2f010 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2f020 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2f030 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2f040 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2f050 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2f060 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2f070 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2f080 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2f090 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f0a0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f0b0 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2f0c0 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2f0d0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2f0e0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2f0f0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2f100 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2f110 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2f120 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2f130 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2f140 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2f150 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2f160 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f170 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2f180 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2f190 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2f1a0 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2f1b0 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2f1c0 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2f1d0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2f1e0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2f1f0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2f200 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2f210 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2f220 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2f230 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2f240 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f250 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2f260 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2f270 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2f280 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f290 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2f2a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2f2b0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2f2c0 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2f2d0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2f2e0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f2f0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2f300 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f310 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f320 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2f330 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f340 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2f350 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2f360 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2f370 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2f380 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2f390 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2f3a0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f3b0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2f3c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f3d0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2f3e0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2f3f0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2f400 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f410 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2f420 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2f430 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f440 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f450 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f460 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2f470 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2f480 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2f490 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2f4a0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2f4b0 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2f4c0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2f4d0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2f4e0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2f4f0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2f500 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2f510 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2f520 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2f530 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2f540 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2f550 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2f560 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f570 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2f580 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2f590 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2f5a0 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2f5b0 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2f5c0 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2f5d0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2f5e0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2f5f0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f600 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2f610 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2f620 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2f630 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2f640 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2f650 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2f660 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2f670 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2f680 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2f690 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f6a0 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2f6b0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f6c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6d0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2f6e0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2f6f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f700 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2f710 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2f720 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2f730 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2f740 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f750 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2f760 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2f770 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2f780 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2f790 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2f7a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f7b0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2f7c0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2f7d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f7e0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2f7f0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2f800 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2f810 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2f820 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2f830 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2f840 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2f850 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2f860 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2f870 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2f880 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2f890 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2f8a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2f8b0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2f8c0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2f8d0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2f8e0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2f8f0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2f900 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2f910 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2f920 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2f930 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2f940 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2f950 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2f960 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f970 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2f980 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2f990 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2f9a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f9b0 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2f9c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2f9d0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2f9e0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f9f0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2fa00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2fa10 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2fa20 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2fa30 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2fa40 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2fa50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2fa60 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2fa70 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2fa80 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2fa90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2faa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2fab0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2fac0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2fad0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fae0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2faf0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2fb00 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fb10 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2fb20 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2fb30 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2fb40 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2fb50 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2fb60 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2fb70 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2fb80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fb90 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2fba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fbb0 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2fbc0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2fbd0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2fbe0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2fbf0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2fc00 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2fc10 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2fc20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2fc30 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2fc40 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2fc50 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2fc60 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2fc70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2fc80 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2fc90 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2fca0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fcb0 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2fcc0 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2fcd0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2fce0 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e   <b>Warning:</b>
2fcf0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2fd00 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fd10 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2fd20 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2fd30 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2fd40 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2fd50 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64  In a multithread
2fd60 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a  ed environment,.
2fd70 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  ** an unprotecte
2fd80 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2fd90 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20  object may only 
2fda0 62 65 20 75 73 65 64 20 73 61 66 65 6c 79 20 77  be used safely w
2fdb0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2fdc0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
2fdd0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
2fde0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
2fdf0 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
2fe00 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2fe10 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2fe20 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
2fe30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
2fe40 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
2fe50 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
2fe60 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
2fe70 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
2fe80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2fe90 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
2fea0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
2feb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
2fec0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
2fed0 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74   behavior is not
2fee0 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a   threadsafe..**.
2fef0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ff00 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
2ff10 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
2ff20 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
2ff30 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
2ff40 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
2ff50 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
2ff60 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
2ff70 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
2ff80 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
2ff90 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2ffa0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
2ffb0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
2ffc0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
2ffd0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
2ffe0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
2fff0 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
30000 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
30010 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
30020 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
30030 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
30040 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
30050 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
30060 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
30070 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
30080 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
30090 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
300a0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
300b0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
300c0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
300d0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
300e0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
300f0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
30100 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
30110 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
30120 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
30130 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
30140 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
30150 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
30160 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
30170 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
30180 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
30190 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
301a0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
301b0 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
301c0 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
301d0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
301e0 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
301f0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
30200 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
30210 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
30220 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
30230 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
30240 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
30250 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
30260 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
30270 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
30280 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
30290 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
302a0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
302b0 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
302c0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
302d0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
302e0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
302f0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
30300 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a  [CAST] to BLOB.*
30310 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
30320 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
30330 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
30340 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
30350 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30360 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30370 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
30380 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  L.** <tr><td>  T
30390 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  EXT    <td>   BL
303a0 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68  OB    <td> No ch
303b0 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ange.** <tr><td>
303c0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49    BLOB    <td> I
303d0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43  NTEGER   <td> [C
303e0 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a  AST] to INTEGER.
303f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
30400 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
30410 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
30420 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c  to REAL.** <tr><
30430 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
30440 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
30450 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d   Add a zero term
30460 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64  inator if needed
30470 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20  .** </table>.** 
30480 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
30490 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
304a0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
304b0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
304c0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
304d0 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
304e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
304f0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
30500 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30510 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
30520 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30530 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
30540 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
30550 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
30560 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
30570 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
30580 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
30590 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
305a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
305b0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
305c0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
305d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
305e0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
305f0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30600 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30610 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
30620 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
30630 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
30640 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
30650 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
30660 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
30670 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
30680 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
30690 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
306a0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
306b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
306c0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
306d0 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
306e0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
306f0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
30700 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
30710 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30720 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
30730 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
30740 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
30750 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
30760 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
30770 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
30780 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
30790 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
307a0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
307b0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
307c0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
307d0 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
307e0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
307f0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
30800 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
30810 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
30820 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
30830 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
30840 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
30850 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
30860 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
30870 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
30880 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
30890 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
308a0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
308b0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
308c0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
308d0 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
308e0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
308f0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
30900 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
30910 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
30920 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
30930 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
30940 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20  afest policy is 
30950 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20  to invoke these 
30960 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f  routines.** in o
30970 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
30980 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ing ways:.**.** 
30990 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  <ul>.**  <li>sql
309a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
309b0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
309c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
309d0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
309e0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
309f0 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65  n_blob() followe
30a00 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30a10 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
30a20 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
30a30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30a40 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
30a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30a60 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  s16()</li>.** </
30a70 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68  ul>.**.** In oth
30a80 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68  er words, you sh
30a90 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65  ould call sqlite
30aa0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
30ab0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30ac0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71  mn_blob(), or sq
30ad0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30ae0 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66  t16() first to f
30af0 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a  orce the result.
30b00 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69  ** into the desi
30b10 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e  red format, then
30b20 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
30b30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f  column_bytes() o
30b40 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
30b50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f  umn_bytes16() to
30b60 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f   find the size o
30b70 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44  f the result.  D
30b80 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a  o not mix calls.
30b90 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ** to sqlite3_co
30ba0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73  lumn_text() or s
30bb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30bc0 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20  ob() with calls 
30bd0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
30be0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20  lumn_bytes16(), 
30bf0 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63  and do not mix c
30c00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
30c10 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a  column_text16().
30c20 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  ** with calls to
30c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30c40 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  bytes()..**.** ^
30c50 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  The pointers ret
30c60 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20  urned are valid 
30c70 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e  until a type con
30c80 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61  version occurs a
30c90 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61  s.** described a
30ca0 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b  bove, or until [
30cb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
30cc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
30cd0 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
30ce0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30cf0 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65  is called.  ^The
30d00 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73   memory space us
30d10 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e  ed to hold strin
30d20 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20  gs.** and BLOBs 
30d30 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74  is freed automat
30d40 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e  ically.  Do <em>
30d50 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68  not</em> pass th
30d60 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
30d70 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
30d80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
30d90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
30da0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
30db0 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
30dc0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
30dd0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
30de0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
30df0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
30e00 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
30e10 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
30e20 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
30e30 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
30e40 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
30e50 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
30e60 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
30e70 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
30e80 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
30e90 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
30ea0 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
30eb0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
30ec0 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
30ed0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
30ee0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
30ef0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20  EM].)^.*/.const 
30f00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
30f10 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65  lumn_blob(sqlite
30f20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30f30 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30f40 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
30f50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
30f60 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
30f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30f80 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
30f90 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62   int iCol);.doub
30fa0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
30fb0 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
30fc0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
30fd0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
30fe0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
30ff0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31000 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  l);.sqlite3_int6
31010 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
31020 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
31030 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31040 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20  .const unsigned 
31050 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
31060 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
31070 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31080 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  l);.const void *
31090 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
310a0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
310b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
310c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
310d0 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  mn_type(sqlite3_
310e0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
310f0 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  ;.sqlite3_value 
31100 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31110 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
31120 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31130 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31140 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
31150 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
31160 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
31170 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
31180 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31190 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
311a0 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
311b0 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
311c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
311d0 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
311e0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
311f0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
31200 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
31210 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
31220 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
31230 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
31240 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
31250 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
31260 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
31270 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
31280 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
31290 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
312a0 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
312b0 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
312c0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
312d0 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
312e0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
312f0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
31300 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
31310 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31320 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
31330 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
31340 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
31350 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
31360 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
31370 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31380 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
31390 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
313a0 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
313b0 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
313c0 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
313d0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
313e0 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
313f0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
31400 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
31410 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
31420 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
31430 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
31440 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
31450 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
31460 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
31470 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
31480 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
31490 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
314a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
314b0 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
314c0 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
314d0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
314e0 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
314f0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
31500 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
31510 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
31520 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
31530 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
31540 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
31550 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
31560 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
31570 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
31580 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
31590 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
315a0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
315b0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
315c0 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
315d0 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
315e0 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
315f0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
31600 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  uption..*/.int s
31610 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31620 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
31630 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
31640 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
31650 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
31660 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
31670 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31680 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
31690 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
316a0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
316b0 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
316c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
316d0 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
316e0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
316f0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
31700 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
31710 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
31720 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
31730 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
31740 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
31750 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
31760 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
31770 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
31780 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
31790 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
317a0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
317b0 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
317c0 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
317d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
317e0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
317f0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
31800 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31810 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
31820 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
31830 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
31840 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
31850 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
31860 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
31870 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
31880 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
31890 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
318a0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
318b0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
318c0 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
318d0 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
318e0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
318f0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
31900 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
31910 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
31920 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
31930 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
31940 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
31950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
31960 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
31970 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31980 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
31990 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
319a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
319b0 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
319c0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
319d0 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
319e0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
319f0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
31a00 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
31a10 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
31a20 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
31a30 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
31a40 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
31a50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
31a60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
31a70 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
31a80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
31a90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
31aa0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
31ab0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
31ac0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
31ad0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
31ae0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
31af0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
31b00 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
31b10 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
31b20 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
31b30 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
31b40 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
31b50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
31b60 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
31b70 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c  ons (collectivel
31b80 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63  y known as "func
31b90 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
31ba0 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20  utines").** are 
31bb0 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20  used to add SQL 
31bc0 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
31bd0 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65  regates or to re
31be0 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76  define the behav
31bf0 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69  ior.** of existi
31c00 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ng SQL functions
31c10 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20   or aggregates. 
31c20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72   The only differ
31c30 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a  ences between.**
31c40 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
31c50 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63  are the text enc
31c60 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66  oding expected f
31c70 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  or.** the second
31c80 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
31c90 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63  name of the func
31ca0 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74  tion being creat
31cb0 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70  ed).** and the p
31cc0 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e  resence or absen
31cd0 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74  ce of a destruct
31ce0 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a  or callback for.
31cf0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31d00 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
31d10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
31d20 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
31d30 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31d40 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63  nection] to whic
31d50 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e  h the SQL.** fun
31d60 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61  ction is to be a
31d70 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70  dded.  ^If an ap
31d80 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d  plication uses m
31d90 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74  ore than one dat
31da0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
31db0 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61  ion then applica
31dc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
31dd0 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20   functions must 
31de0 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65  be added.** to e
31df0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
31e00 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65  nection separate
31e10 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
31e20 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
31e30 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
31e40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
31e50 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72  to be created or
31e60 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20  .** redefined.  
31e70 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74  ^The length of t
31e80 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74  he name is limit
31e90 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20  ed to 255 bytes 
31ea0 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65  in a UTF-8.** re
31eb0 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78  presentation, ex
31ec0 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a  clusive of the z
31ed0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero-terminator. 
31ee0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
31ef0 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c  name.** length l
31f00 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38  imit is in UTF-8
31f10 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72   bytes, not char
31f20 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31  acters nor UTF-1
31f30 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41  6 bytes.  .** ^A
31f40 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72  ny attempt to cr
31f50 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20  eate a function 
31f60 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61  with a longer na
31f70 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c  me.** will resul
31f80 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  t in [SQLITE_MIS
31f90 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72  USE] being retur
31fa0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
31fb0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
31fc0 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65  (nArg).** is the
31fd0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
31fe0 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51  ents that the SQ
31ff0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32000 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73   aggregate takes
32010 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d  . ^If this param
32020 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eter is -1, then
32030 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32040 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
32050 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e  e may take any n
32060 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
32070 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64  ts between 0 and
32080 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65   the limit.** se
32090 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69  t by [sqlite3_li
320a0 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d  mit]([SQLITE_LIM
320b0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
320c0 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64  ).  If the third
320d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73  .** parameter is
320e0 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72   less than -1 or
320f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32   greater than 12
32100 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  7 then the behav
32110 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69  ior is.** undefi
32120 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
32130 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32140 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63  , eTextRep, spec
32150 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53  ifies what.** [S
32160 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78  QLITE_UTF8 | tex
32170 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73  t encoding] this
32180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72   SQL function pr
32190 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73  efers for.** its
321a0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68   parameters.  Th
321b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
321c0 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61  ould set this pa
321d0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53  rameter to.** [S
321e0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69  QLITE_UTF16LE] i
321f0 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
32200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
32210 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74  vokes .** [sqlit
32220 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
32230 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
32240 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
32250 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20  16BE] if the.** 
32260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
32270 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f  nvokes [sqlite3_
32280 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29  value_text16be()
32290 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
322a0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  r.** [SQLITE_UTF
322b0 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  16] if [sqlite3_
322c0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
322d0 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c  is used, or [SQL
322e0 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68  ITE_UTF8].** oth
322f0 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61  erwise.  ^The sa
32300 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
32310 6d 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65  may be registere
32320 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  d multiple times
32330 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72   using.** differ
32340 65 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65  ent preferred te
32350 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69  xt encodings, wi
32360 74 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70  th different imp
32370 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72  lementations for
32380 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e  .** each encodin
32390 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  g..** ^When mult
323a0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
323b0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
323c0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
323d0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
323e0 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
323f0 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
32400 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
32410 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
32420 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ersion..**.** ^T
32430 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
32440 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c  ter may optional
32450 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20  ly be ORed with 
32460 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
32470 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67  ISTIC].** to sig
32480 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e  nal that the fun
32490 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79  ction will alway
324a0 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
324b0 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a  e result given.*
324c0 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  * the same input
324d0 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  s within a singl
324e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
324f0 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74    Most SQL funct
32500 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65  ions are.** dete
32510 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
32520 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d  built-in [random
32530 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
32540 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f   is an example o
32550 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  f a.** function 
32560 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65  that is not dete
32570 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20  rministic.  The 
32580 53 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61  SQLite query pla
32590 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a  nner is able to.
325a0 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74  ** perform addit
325b0 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69  ional optimizati
325c0 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69  ons on determini
325d0 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20  stic functions, 
325e0 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65  so use.** of the
325f0 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49   [SQLITE_DETERMI
32600 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20  NISTIC] flag is 
32610 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72  recommended wher
32620 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a  e possible..**.*
32630 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
32640 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
32650 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
32660 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
32670 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
32680 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
32690 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
326a0 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
326b0 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
326c0 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
326d0 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
326e0 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
326f0 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
32700 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
32710 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
32720 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
32730 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
32740 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
32750 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
32760 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
32770 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
32780 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
32790 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
327a0 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
327b0 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
327c0 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
327d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
327e0 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
327f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
32800 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
32810 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
32820 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
32830 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
32840 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
32850 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
32860 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
32870 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
32880 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
32890 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
328a0 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
328b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
328c0 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
328d0 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
328e0 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
328f0 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
32900 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
32910 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
32920 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
32930 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
32940 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
32950 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
32960 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
32970 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
32980 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
32990 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
329a0 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
329b0 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
329c0 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
329d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
329e0 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
329f0 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
32a00 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
32a10 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
32a20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
32a30 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
32a40 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
32a50 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
32a60 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
32a70 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
32a80 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
32a90 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
32aa0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
32ab0 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
32ac0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32ad0 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
32ae0 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
32af0 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
32b00 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
32b10 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
32b20 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
32b30 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
32b40 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
32b50 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32b60 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
32b70 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
32b80 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
32b90 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
32ba0 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
32bb0 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
32bc0 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
32bd0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
32be0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
32bf0 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
32c00 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
32c10 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
32c20 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
32c30 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
32c40 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
32c50 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
32c60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
32c70 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
32c80 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
32c90 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
32ca0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
32cb0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32cc0 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
32cd0 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
32ce0 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
32cf0 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
32d00 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
32d10 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
32d20 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
32d30 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
32d40 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32d50 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
32d60 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
32d70 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
32d80 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
32d90 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
32da0 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
32db0 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
32dc0 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
32dd0 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
32de0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
32df0 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
32e00 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
32e10 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
32e20 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
32e30 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
32e40 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
32e50 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
32e60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32e70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
32e80 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32e90 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
32ea0 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
32eb0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
32ec0 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
32ed0 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
32ee0 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
32ef0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
32f00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
32f10 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
32f20 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
32f30 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
32f40 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
32f50 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32f60 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
32f70 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20  ate_function(.  
32f80 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
32f90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
32fa0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
32fb0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
32fc0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
32fd0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
32fe0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
32ff0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33000 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33010 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33020 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33030 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33040 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33050 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33060 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  xt*).);.int sqli
33070 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33080 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
33090 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
330a0 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
330b0 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
330c0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
330d0 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
330e0 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
330f0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
33100 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
33110 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
33120 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
33130 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33140 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33150 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
33160 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
33170 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
33180 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
33190 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
331a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
331b0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
331c0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
331d0 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
331e0 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
331f0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33200 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33210 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33220 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33230 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33240 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33250 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
33260 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
33270 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28  ntext*),.  void(
33280 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a  *xDestroy)(void*
33290 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ).);../*.** CAPI
332a0 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64  3REF: Text Encod
332b0 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ings.**.** These
332c0 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65   constant define
332d0 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74   integer codes t
332e0 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68  hat represent th
332f0 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78  e various.** tex
33300 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70  t encodings supp
33310 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  orted by SQLite.
33320 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
33330 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20  TE_UTF8         
33340 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52    1    /* IMP: R
33350 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a  -37514-35566 */.
33360 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
33370 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 20  TF16LE        2 
33380 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33     /* IMP: R-033
33390 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65 66  71-37637 */.#def
333a0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
333b0 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20 2f  BE        3    /
333c0 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33  * IMP: R-51971-3
333d0 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  4154 */.#define 
333e0 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20  SQLITE_UTF16    
333f0 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73        4    /* Us
33400 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  e native byte or
33410 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  der */.#define S
33420 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20  QLITE_ANY       
33430 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65 70       5    /* Dep
33440 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66 69  recated */.#defi
33450 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
33460 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
33470 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33480 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
33490 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
334a0 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67  F: Function Flag
334b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
334c0 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20 4f  nstants may be O
334d0 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69 74  Red together wit
334e0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
334f0 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72 72  E_UTF8 | preferr
33500 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
33510 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  ] as the fourth 
33520 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b  argument.** to [
33530 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33540 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c  unction()], [sql
33550 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33560 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  tion16()], or.**
33570 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
33580 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e  _function_v2()].
33590 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
335a0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
335b0 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a      0x800../*.**
335c0 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65   CAPI3REF: Depre
335d0 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a  cated Functions.
335e0 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a  ** DEPRECATED.**
335f0 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69  .** These functi
33600 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61  ons are [depreca
33610 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20  ted].  In order 
33620 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62  to maintain.** b
33630 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
33640 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65  bility with olde
33650 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75  r code, these fu
33660 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65  nctions continue
33670 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f   .** to be suppo
33680 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20  rted.  However, 
33690 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
336a0 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a   should avoid.**
336b0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73   the use of thes
336c0 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f  e functions.  To
336d0 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67 72   encourage progr
336e0 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64 0a  ammers to avoid.
336f0 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  ** these functio
33700 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20  ns, we will not 
33710 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68 65  explain what the
33720 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
33730 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
33740 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 44  RECATED.SQLITE_D
33750 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
33770 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  count(sqlite3_co
33780 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
33790 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
337a0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
337b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
337c0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
337d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
337e0 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
337f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
33800 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
33810 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
33820 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62  int sqlite3_glob
33830 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29  al_recover(void)
33840 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
33850 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33  TED void sqlite3
33860 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28  _thread_cleanup(
33870 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
33880 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
33890 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
338a0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
338b0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
338c0 74 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  t),.            
338d0 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c            void*,
338e0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
338f0 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
33900 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
33910 67 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20  g SQL Values.** 
33920 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
33930 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
33940 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
33950 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
33960 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
33970 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
33980 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
33990 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
339a0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
339b0 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
339c0 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
339d0 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
339e0 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75    .**.** The xFu
339f0 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
33a00 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
33a10 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
33a20 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
33a30 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
33a40 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33a50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
33a60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
33a70 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
33a80 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
33a90 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
33aa0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
33ab0 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
33ac0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33ad0 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
33ae0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
33af0 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
33b00 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
33b10 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
33b20 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
33b30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33b40 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
33b50 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
33b60 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
33b70 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
33b80 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
33b90 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
33ba0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
33bb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
33bc0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
33bd0 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
33be0 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
33bf0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33c00 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
33c10 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
33c20 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
33c30 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
33c40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
33c50 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
33c60 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
33c70 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
33c80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
33c90 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
33ca0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
33cb0 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
33cc0 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
33cd0 70 74 20 74 68 61 74 20 74 68 65 73 65 20 72 6f  pt that these ro
33ce0 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
33cf0 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
33d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33d10 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
33d20 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
33d30 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
33d40 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
33d50 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
33d60 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
33d70 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33d80 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
33d90 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
33da0 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
33db0 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
33dc0 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
33dd0 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
33de0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
33df0 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
33e00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33e10 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
33e20 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
33e30 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
33e40 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
33e50 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
33e60 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
33e70 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
33e80 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
33e90 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
33ea0 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
33eb0 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
33ec0 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
33ed0 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
33ee0 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
33ef0 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
33f00 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
33f10 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
33f20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
33f30 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
33f40 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
33f50 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
33f60 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
33f70 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
33f80 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
33f90 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
33fa0 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
33fb0 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
33fc0 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
33fd0 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
33fe0 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
33ff0 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
34000 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
34010 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
34020 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
34030 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
34040 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
34050 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
34060 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
34070 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
34080 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
34090 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
340a0 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
340b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
340c0 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
340d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
340e0 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
340f0 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
34100 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
34110 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
34120 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
34130 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
34140 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
34150 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
34160 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
34170 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
34180 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34190 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
341a0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
341b0 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
341c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
341d0 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
341e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
341f0 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
34200 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34210 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
34220 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34230 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34240 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
34250 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
34260 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
34270 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
34280 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
34290 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
342a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
342b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
342c0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
342d0 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
342e0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
342f0 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
34300 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
34310 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
34320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34330 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
34340 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
34350 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
34360 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
34370 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
34380 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
34390 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
343a0 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
343b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
343c0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
343d0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
343e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
343f0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34400 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
34410 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
34420 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34430 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
34440 49 33 52 45 46 3a 20 46 69 6e 64 69 6e 67 20 54  I3REF: Finding T
34450 68 65 20 53 75 62 74 79 70 65 20 4f 66 20 53 51  he Subtype Of SQ
34460 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
34470 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
34480 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
34490 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
344a0 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(V) function re
344b0 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70  turns the subtyp
344c0 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 5b 61 70 70  e for.** an [app
344d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
344e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 61   SQL function] a
344f0 72 67 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20  rgument V.  The 
34500 73 75 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72  subtype.** infor
34510 6d 61 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  mation can be us
34520 65 64 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d  ed to pass a lim
34530 69 74 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63  ited amount of c
34540 6f 6e 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f  ontext from.** o
34550 6e 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ne SQL function 
34560 74 6f 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65  to another.  Use
34570 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
34580 73 75 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a  sult_subtype()].
34590 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65  ** routine to se
345a0 74 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f  t the subtype fo
345b0 72 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  r the return val
345c0 75 65 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e  ue of an SQL fun
345d0 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ction..**.** SQL
345e0 69 74 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65  ite makes no use
345f0 20 6f 66 20 73 75 62 74 79 70 65 20 69 74 73 65   of subtype itse
34600 6c 66 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70  lf.  It merely p
34610 61 73 73 65 73 20 74 68 65 20 73 75 62 74 79 70  asses the subtyp
34620 65 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65  e.** from the re
34630 73 75 6c 74 20 6f 66 20 6f 6e 65 20 5b 61 70 70  sult of one [app
34640 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34650 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 20 69   SQL function] i
34660 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74  nto the.** input
34670 20 6f 66 20 61 6e 6f 74 68 65 72 2e 0a 2a 2f 0a   of another..*/.
34680 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 71 6c  unsigned int sql
34690 69 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79  ite3_value_subty
346a0 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
346b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
346c0 52 45 46 3a 20 43 6f 70 79 20 41 6e 64 20 46 72  REF: Copy And Fr
346d0 65 65 20 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a  ee SQL Values.**
346e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
346f0 5f 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  _value.**.** ^Th
34700 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
34710 64 75 70 28 56 29 20 69 6e 74 65 72 66 61 63 65  dup(V) interface
34720 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
34730 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
34740 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 44  lue].** object D
34750 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
34760 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 63  ointer to that c
34770 6f 70 79 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  opy.  ^The [sqli
34780 74 65 33 5f 76 61 6c 75 65 5d 20 72 65 74 75 72  te3_value] retur
34790 6e 65 64 0a 2a 2a 20 69 73 20 61 20 5b 70 72 6f  ned.** is a [pro
347a0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
347b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 65 76 65  alue] object eve
347c0 6e 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 69  n if the input i
347d0 73 20 6e 6f 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  s not..** ^The s
347e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
347f0 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (V) interface re
34800 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66 20 56 20  turns NULL if V 
34810 69 73 20 4e 55 4c 4c 20 6f 72 20 69 66 20 61 0a  is NULL or if a.
34820 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
34830 74 69 6f 6e 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  tion fails..**.*
34840 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
34850 61 6c 75 65 5f 66 72 65 65 28 56 29 20 69 6e 74  alue_free(V) int
34860 65 72 66 61 63 65 20 66 72 65 65 73 20 61 6e 20  erface frees an 
34870 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
34880 6f 62 6a 65 63 74 0a 2a 2a 20 70 72 65 76 69 6f  object.** previo
34890 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
348a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
348b0 65 5f 64 75 70 28 29 5d 2e 20 20 5e 49 66 20 56  e_dup()].  ^If V
348c0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
348d0 65 72 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  er.** then sqlit
348e0 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 56 29  e3_value_free(V)
348f0 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
34900 6f 2d 6f 70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33  o-op..*/.sqlite3
34910 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
34920 76 61 6c 75 65 5f 64 75 70 28 63 6f 6e 73 74 20  value_dup(const 
34930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34940 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61  .void sqlite3_va
34950 6c 75 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33  lue_free(sqlite3
34960 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
34970 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
34980 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63  n Aggregate Func
34990 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20  tion Context.** 
349a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
349b0 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d  context.**.** Im
349c0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66  plementations of
349d0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
349e0 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69  unctions use thi
349f0 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20  s.** routine to 
34a00 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
34a10 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69  for storing thei
34a20 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  r state..**.** ^
34a30 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
34a40 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
34a50 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34a60 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c  ) routine is cal
34a70 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61  led .** for a pa
34a80 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61  rticular aggrega
34a90 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c  te function, SQL
34aa0 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73  ite.** allocates
34ab0 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65   N of memory, ze
34ac0 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65  roes out that me
34ad0 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e  mory, and return
34ae0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
34af0 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79  o the new memory
34b00 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64  . ^On second and
34b10 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
34b20 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
34b30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34b40 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65  t() for the same
34b50 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34b60 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a  ion instance,.**
34b70 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72   the same buffer
34b80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53   is returned.  S
34b90 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34ba0 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f  _context() is no
34bb0 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  rmally.** called
34bc0 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69   once for each i
34bd0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65  nvocation of the
34be0 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20   xStep callback 
34bf0 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20  and then one.** 
34c00 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74  last time when t
34c10 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
34c20 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20  ck is invoked.  
34c30 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d  ^(When no rows m
34c40 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65  atch.** an aggre
34c50 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20  gate query, the 
34c60 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b  xStep() callback
34c70 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74   of the aggregat
34c80 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d  e function.** im
34c90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
34ca0 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64  never called and
34cb0 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c   xFinal() is cal
34cc0 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65  led exactly once
34cd0 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61  ..** In those ca
34ce0 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67  ses, sqlite3_agg
34cf0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
34d00 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64   might be called
34d10 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73   for the.** firs
34d20 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68  t time from with
34d30 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a  in xFinal().)^.*
34d40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34d50 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34d60 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
34d70 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
34d80 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e  pointer .** when
34d90 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66   first called if
34da0 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20   N is less than 
34db0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
34dc0 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a   or if a memory.
34dd0 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ** allocate erro
34de0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
34df0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
34e00 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
34e10 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
34e20 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
34e30 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
34e40 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
34e50 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
34e60 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
34e70 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
34e80 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
34e90 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
34ea0 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
34eb0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
34ec0 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
34ed0 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
34ee0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
34ef0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
34f00 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
34f10 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e  ation.)^  Within
34f20 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
34f30 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74  back, it is cust
34f40 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20  omary to set.** 
34f50 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20  N=0 in calls to 
34f60 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34f70 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73  e_context(C,N) s
34f80 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f  o that no .** po
34f90 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61  intless memory a
34fa0 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72  llocations occur
34fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
34fc0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72  automatically fr
34fd0 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ees the memory a
34fe0 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20  llocated by .** 
34ff0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35000 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e  e_context() when
35010 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71   the aggregate q
35020 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a  uery concludes..
35030 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
35040 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
35050 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  e a copy of the.
35060 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
35070 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69  ext | SQL functi
35080 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74  on context] that
35090 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
350a0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
350b0 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61  e xStep or xFina
350c0 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69  l callback routi
350d0 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ne that implemen
350e0 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ts the aggregate
350f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  .** function..**
35100 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35110 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35120 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
35130 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
35140 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53   the aggregate S
35150 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35160 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20  unning..*/.void 
35170 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  *sqlite3_aggrega
35180 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74  te_context(sqlit
35190 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
351a0 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a   nBytes);../*.**
351b0 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20   CAPI3REF: User 
351c0 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f  Data For Functio
351d0 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ns.** METHOD: sq
351e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a  lite3_context.**
351f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
35200 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
35210 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
35220 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
35230 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
35240 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
35250 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
35260 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
35270 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
35280 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
35290 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
352a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
352b0 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
352c0 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
352d0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
352e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
352f0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
35300 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
35310 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
35320 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
35330 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
35340 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35350 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35360 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
35370 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
35380 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
35390 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
353a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
353b0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
353c0 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
353d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
353e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
353f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35400 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35410 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
35420 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
35430 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
35440 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
35450 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65  connection] (the
35460 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a   1st parameter).
35470 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
35480 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35490 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  on()].** and [sq
354a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
354b0 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69  ction16()] routi
354c0 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61  nes that origina
354d0 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  lly.** registere
354e0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
354f0 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n defined functi
35500 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a  on..*/.sqlite3 *
35510 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
35520 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
35530 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
35540 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
35550 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
35560 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
35570 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
35580 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
35590 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
355a0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
355b0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
355c0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
355d0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
355e0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
355f0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
35600 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
35610 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
35620 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
35630 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
35640 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
35650 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
35660 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
35670 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
35680 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
35690 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
356a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
356b0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
356c0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
356d0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
356e0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
356f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
35700 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
35710 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
35720 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
35730 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
35740 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
35750 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
35760 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
35770 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
35780 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
35790 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
357a0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
357b0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
357c0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
357d0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
357e0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
357f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
35800 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
35820 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35830 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
35840 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
35850 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
35860 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
35870 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35880 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
35890 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
358a0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
358b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
358c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
358d0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
358e0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
358f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
35900 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
35910 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
35920 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
35930 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
35940 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
35950 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35960 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
35970 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
35980 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
35990 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
359a0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
359b0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
359c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
359d0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
359e0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
359f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35a00 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
35a10 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
35a20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
35a30 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
35a40 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
35a50 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
35a60 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
35a70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
35a80 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
35a90 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
35aa0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
35ab0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35ac0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
35ad0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
35ae0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
35af0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
35b00 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
35b10 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
35b20 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
35b30 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
35b40 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
35b50 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
35b60 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
35b70 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
35b80 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
35b90 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
35ba0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
35bb0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
35bc0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
35bd0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
35be0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
35bf0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
35c00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
35c10 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
35c20 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
35c30 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
35c40 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
35c50 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35c60 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
35c70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
35c80 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
35c90 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
35ca0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
35cb0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
35cc0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
35cd0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
35ce0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
35cf0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
35d00 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
35d10 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
35d20 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
35d30 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
35d40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
35d50 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
35d60 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
35d70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
35d80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
35d90 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
35da0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
35db0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
35dc0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
35dd0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
35de0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
35df0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
35e00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35e10 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
35e20 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
35e30 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
35e40 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
35e50 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
35e60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
35e70 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
35e80 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
35e90 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
35ea0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
35eb0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
35ec0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
35ed0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
35ee0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
35ef0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
35f00 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
35f10 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
35f20 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
35f30 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
35f40 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
35f50 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
35f60 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
35f70 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
35f80 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
35f90 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
35fa0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
35fb0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
35fc0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35fd0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35fe0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
35ff0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
36000 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
36010 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
36020 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
36030 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
36040 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
36050 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
36060 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
36070 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
36080 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
36090 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
360a0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
360b0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
360c0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
360d0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
360e0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
360f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
36100 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
36110 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
36120 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
36130 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
36140 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
36150 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
36160 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
36170 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
36180 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
36190 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
361a0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
361b0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
361c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
361d0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
361e0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
361f0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
36200 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
36210 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
36220 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
36230 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
36240 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
36250 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
36260 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
36270 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
36280 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
36290 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
362a0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
362b0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
362c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
362d0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
362e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
362f0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
36300 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
36310 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
36320 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
36330 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
36340 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
36350 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
36360 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
36370 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
36380 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  n.** METHOD: sql
36390 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a  ite3_context.**.
363a0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
363b0 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68  s are used by th
363c0 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61  e xFunc or xFina
363d0 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  l callbacks that
363e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51  .** implement SQ
363f0 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
36400 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65  aggregates.  See
36410 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
36420 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
36430 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
36440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
36450 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f  ].** for additio
36460 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
36470 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
36480 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79  ctions work very
36490 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b   much like the [
364a0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
364b0 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  g] family of.** 
364c0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74  functions used t
364d0 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  o bind values to
364e0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
364f0 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61   in prepared sta
36500 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65  tements..** Refe
36510 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61  r to the [SQL pa
36520 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e  rameter] documen
36530 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74  tation for addit
36540 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
36550 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
36560 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
36570 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  b() interface se
36580 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
36590 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
365a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
365b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
365c0 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65  BLOB whose conte
365d0 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a  nt is pointed.**
365e0 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e   to by the secon
365f0 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  d parameter and 
36600 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73  which is N bytes
36610 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73   long where N is
36620 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61   the.** third pa
36630 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
36640 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36650 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29  lt_zeroblob(C,N)
36660 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
36670 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43  ult_zeroblob64(C
36680 2c 4e 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ,N).** interface
36690 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
366a0 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
366b0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
366c0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20  tion to be.** a 
366d0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
366e0 61 6c 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61  all zero bytes a
366f0 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
36700 7a 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ze..**.** ^The s
36710 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
36720 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  uble() interface
36730 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
36740 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
36750 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36760 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
36770 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
36780 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a  value specified.
36790 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72  ** by its 2nd ar
367a0 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
367b0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
367c0 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
367d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
367e0 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73  or16() functions
367f0 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d  .** cause the im
36800 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75  plemented SQL fu
36810 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20  nction to throw 
36820 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a  an exception..**
36830 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
36840 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64  e string pointed
36850 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e   to by the.** 2n
36860 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
36870 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36880 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ror() or sqlite3
36890 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
368a0 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74  ).** as the text
368b0 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73   of an error mes
368c0 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69  sage.  ^SQLite i
368d0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72  nterprets the er
368e0 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73  ror.** message s
368f0 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
36900 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
36910 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c  ) as UTF-8. ^SQL
36920 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ite.** interpret
36930 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f  s the string fro
36940 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  m sqlite3_result
36950 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54  _error16() as UT
36960 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a  F-16 in native.*
36970 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e  * byte order.  ^
36980 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
36990 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
369a0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
369b0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
369c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
369d0 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  is negative then
369e0 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73   SQLite takes as
369f0 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65   the error.** me
36a00 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75  ssage all text u
36a10 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69  p through the fi
36a20 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74  rst zero charact
36a30 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
36a40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
36a50 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36a60 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73  _error() or.** s
36a70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36a80 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e  ror16() is non-n
36a90 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
36aa0 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d  ite takes that m
36ab0 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f  any.** bytes (no
36ac0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72  t characters) fr
36ad0 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  om the 2nd param
36ae0 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f  eter as the erro
36af0 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54  r message..** ^T
36b00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36b10 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71  t_error() and sq
36b20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36b30 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  or16().** routin
36b40 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74  es make a privat
36b50 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72  e copy of the er
36b60 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74  ror message text
36b70 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20   before.** they 
36b80 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20  return.  Hence, 
36b90 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63  the calling func
36ba0 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63  tion can dealloc
36bb0 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79  ate or.** modify
36bc0 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20   the text after 
36bd0 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68  they return with
36be0 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68  out harm..** ^Th
36bf0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36c00 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75  _error_code() fu
36c10 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74  nction changes t
36c20 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a  he error code.**
36c30 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c   returned by SQL
36c40 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20  ite as a result 
36c50 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61  of an error in a
36c60 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20   function.  ^By 
36c70 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20  default,.** the 
36c80 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51  error code is SQ
36c90 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20  LITE_ERROR.  ^A 
36ca0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
36cb0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
36cc0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
36cd0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36ce0 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20  rror16() resets 
36cf0 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74  the error code t
36d00 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a  o SQLITE_ERROR..
36d10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36d20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
36d30 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61  toobig() interfa
36d40 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
36d50 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
36d60 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
36d70 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f   that a string o
36d80 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f  r BLOB is too lo
36d90 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e  ng to represent.
36da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36db0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36dc0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
36dd0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
36de0 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20   to throw an.** 
36df0 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67  error indicating
36e00 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
36e10 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
36e20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36e30 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
36e40 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36e50 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
36e60 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
36e70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
36e80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
36e90 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
36ea0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
36eb0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
36ec0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
36ed0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36ee0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
36ef0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36f00 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
36f10 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36f20 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36f30 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
36f40 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
36f50 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
36f60 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
36f70 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36f80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36f90 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
36fa0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
36fb0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
36fc0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
36fd0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
36fe0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
36ff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37000 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
37010 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37020 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
37030 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
37040 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
37050 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
37060 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
37070 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
37080 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
37090 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
370a0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
370b0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
370c0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
370d0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
370e0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
370f0 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
37100 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
37110 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
37120 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
37130 76 65 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  vely..** ^The sq
37140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37150 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
37160 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
37170 76 61 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61  value of an.** a
37180 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37190 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
371a0 65 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  e a text string 
371b0 69 6e 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a  in an encoding.*
371c0 2a 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  * specified by t
371d0 68 65 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61  he fifth (and la
371e0 73 74 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77  st) parameter, w
371f0 68 69 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65  hich must be one
37200 0a 2a 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  .** of [SQLITE_U
37210 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
37220 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
37230 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
37240 54 45 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20  TE_UTF16LE]..** 
37250 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
37260 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
37270 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
37280 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
37290 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
372a0 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
372b0 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
372c0 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
372d0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
372e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
372f0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
37300 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
37310 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
37320 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
37330 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
37340 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
37350 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
37360 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
37370 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
37380 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37390 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
373a0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
373b0 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
373c0 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
373d0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
373e0 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
373f0 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
37400 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
37410 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
37420 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
37430 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
37440 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20  nction result.  
37450 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37460 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  eter is non-nega
37470 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a  tive, then it.**
37480 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
37490 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68  e offset into th
374a0 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74  e string where t
374b0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
374c0 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61  r would.** appea
374d0 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  r if the string 
374e0 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e  where NUL termin
374f0 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
37500 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
37510 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72  ur.** in the str
37520 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66  ing at a byte of
37530 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73  fset that is les
37540 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65  s than the value
37550 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70   of the 3rd.** p
37560 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74  arameter, then t
37570 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
37580 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e  ing will contain
37590 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61   embedded NULs a
375a0 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  nd the.** result
375b0 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20   of expressions 
375c0 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72  operating on str
375d0 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64  ings with embedd
375e0 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66  ed NULs is undef
375f0 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ined..** ^If the
37600 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
37610 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37620 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37630 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69  faces.** or sqli
37640 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
37650 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  is a non-NULL po
37660 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69  inter, then SQLi
37670 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a  te calls that.**
37680 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65   function as the
37690 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74   destructor on t
376a0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
376b0 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68  result when it h
376c0 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75  as.** finished u
376d0 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
376e0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
376f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37700 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37710 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37720 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  s or to.** sqlit
37730 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
37740 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f  s the special co
37750 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54  nstant SQLITE_ST
37760 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74  ATIC, then SQLit
37770 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61  e.** assumes tha
37780 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  t the text or BL
37790 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20  OB result is in 
377a0 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61  constant space a
377b0 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63  nd does not.** c
377c0 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  opy the content 
377d0 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
377e0 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74   nor call a dest
377f0 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f  ructor on the co
37800 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74  ntent.** when it
37810 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73   has finished us
37820 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
37830 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
37840 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37850 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37860 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37870 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  .** or sqlite3_r
37880 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
37890 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
378a0 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  nt SQLITE_TRANSI
378b0 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69  ENT.** then SQLi
378c0 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  te makes a copy 
378d0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e  of the result in
378e0 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65  to space obtaine
378f0 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b  d from.** from [
37900 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
37910 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75  ] before it retu
37920 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
37930 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37940 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
37950 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
37960 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
37970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
37980 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
37990 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
379a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
379b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
379c0 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
379d0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
379e0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
379f0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37a00 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
37a10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37a20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
37a30 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
37a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
37a50 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
37a60 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
37a70 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
37a80 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
37a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
37aa0 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
37ab0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
37ac0 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
37ad0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37ae0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
37af0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
37b00 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
37b10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
37b20 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
37b30 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
37b40 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
37b50 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
37b60 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
37b70 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
37b80 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
37b90 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
37ba0 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
37bb0 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
37bc0 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
37bd0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
37be0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37bf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
37c00 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
37c10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
37c20 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
37c30 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
37c40 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
37c50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37c60 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
37c70 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37c80 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
37c90 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
37ca0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37cb0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63  blob64(sqlite3_c
37cc0 6f 6e 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f  ontext*,const vo
37cd0 69 64 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  id*,.           
37ce0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37cf0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76  sqlite3_uint64,v
37d00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37d10 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37d20 75 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ult_double(sqlit
37d30 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75  e3_context*, dou
37d40 62 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ble);.void sqlit
37d50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
37d60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37d70 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
37d80 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
37d90 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
37da0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37db0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
37dc0 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  int);.void sqlit
37dd0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37de0 74 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63  toobig(sqlite3_c
37df0 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
37e00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
37e10 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65  ror_nomem(sqlite
37e20 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69  3_context*);.voi
37e30 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37e40 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
37e50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37e60 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37e70 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
37e80 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37e90 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37ea0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71  _result_int64(sq
37eb0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37ec0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
37ed0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37ee0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
37ef0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
37f00 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37f10 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  text(sqlite3_con
37f20 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37f30 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  r*, int, void(*)
37f40 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37f50 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37f60 78 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  xt64(sqlite3_con
37f70 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
37f80 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
37f90 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
37fa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
37fb0 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
37fc0 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
37fd0 64 69 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ding);.void sqli
37fe0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37ff0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
38000 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
38010 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f   int, void(*)(vo
38020 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
38030 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
38040 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6le(sqlite3_cont
38050 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
38060 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
38070 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
38080 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38090 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
380a0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
380b0 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
380c0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
380d0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
380e0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
380f0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
38100 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  ue*);.void sqlit
38110 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
38120 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ob(sqlite3_conte
38130 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74  xt*, int n);.int
38140 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38150 7a 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74  zeroblob64(sqlit
38160 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
38170 69 74 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a  ite3_uint64 n);.
38180 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38190 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 53 75  : Setting The Su
381a0 62 74 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20  btype Of An SQL 
381b0 46 75 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48  Function.** METH
381c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  OD: sqlite3_cont
381d0 65 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ext.**.** The sq
381e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62  lite3_result_sub
381f0 74 79 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69  type(C,T) functi
38200 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 73 75  on causes the su
38210 62 74 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20  btype of.** the 
38220 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
38230 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
38240 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
38250 6e 5d 20 77 69 74 68 20 0a 2a 2a 20 5b 73 71 6c  n] with .** [sql
38260 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 43 20  ite3_context] C 
38270 74 6f 20 62 65 20 74 68 65 20 76 61 6c 75 65 20  to be the value 
38280 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20 6c 6f 77  T.  Only the low
38290 65 72 20 38 20 62 69 74 73 20 0a 2a 2a 20 6f 66  er 8 bits .** of
382a0 20 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61   the subtype T a
382b0 72 65 20 70 72 65 73 65 72 76 65 64 20 69 6e 20  re preserved in 
382c0 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f 6e 73  current versions
382d0 20 6f 66 20 53 51 4c 69 74 65 3b 0a 2a 2a 20 68   of SQLite;.** h
382e0 69 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73  igher order bits
382f0 20 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a   are discarded..
38300 2a 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** The number of
38310 20 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70   subtype bytes p
38320 72 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69  reserved by SQLi
38330 74 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73  te might increas
38340 65 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72  e.** in future r
38350 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
38360 65 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  e..*/.void sqlit
38370 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70  e3_result_subtyp
38380 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
38390 74 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29  t*,unsigned int)
383a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
383b0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
383c0 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
383d0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
383e0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ite3.**.** ^Thes
383f0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
38400 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
38410 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
38420 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
38430 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
38440 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
38450 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
38460 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
38470 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
38480 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
38490 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
384a0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
384b0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
384c0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
384d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
384e0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
384f0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
38500 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38510 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
38520 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
38530 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
38540 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
38550 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
38560 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
38570 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
38580 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
38590 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
385a0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
385b0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
385c0 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
385d0 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
385e0 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
385f0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38600 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
38610 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
38620 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
38630 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
38640 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
38650 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
38660 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
38670 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
38680 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
38690 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
386a0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
386b0 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
386c0 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
386d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
386e0 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
386f0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
38700 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
38710 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
38720 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
38730 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
38740 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
38750 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
38760 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38770 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
38780 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38790 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
387a0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
387b0 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
387c0 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
387d0 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
387e0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
387f0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
38800 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38810 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
38820 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
38830 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
38840 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
38850 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
38860 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a