/ Hex Artifact Content
Login

Artifact 65ff1449e8c181da9ec752e8304e0a1efffaf47f:


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 69 6e 73  er, and thus ins
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 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure 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 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
55f0: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
5600: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
5610: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5620: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
5630: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5640: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
5650: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5660: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
5670: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5680: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
5690: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56a0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
56b0: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
56c0: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
56d0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
56e0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
56f0: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
5700: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
5710: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5720: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
5730: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
5740: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
5750: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5760: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
5770: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
5780: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
5790: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
57a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
57b0: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
57c0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
57d0: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
57e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
57f0: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
5800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
5810: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
5820: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
5830: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
5840: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
5850: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
5860: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5870: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
5880: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
5890: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
58a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
58b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
58c0: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
58d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
58e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
58f0: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
5900: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
5910: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
5920: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5930: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
5940: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
5950: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5960: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5970: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5980: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
5990: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
59a0: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
59b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
59c0: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
59d0: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
59e0: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
59f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5a00: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
5a10: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
5a20: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
5a30: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a40: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
5a50: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
5a60: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5a70: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
5a80: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5a90: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
5aa0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5ab0: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
5ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
5ad0: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
5ae0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
5af0: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
5b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5b10: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
5b20: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
5b30: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
5b40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5b50: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
5b60: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
5b70: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
5b80: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5b90: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
5ba0: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
5bb0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
5bc0: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
5bd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
5be0: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
5bf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
5c00: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<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 52 4f 4c 4c 42  CE_RECOVER_ROLLB
5c30: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
5c40: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
5c60: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
5c70: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
5c80: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
5c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
5ca0: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
5cb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
5cc0: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
5cd0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
5ce0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
5cf0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
5d00: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
5d10: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
5d20: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
5d30: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
5d40: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
5d50: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
5d60: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
5d70: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
5d80: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
5d90: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
5da0: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
5db0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
5dc0: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
5dd0: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
5de0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5df0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
5e10: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
5e20: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
5e30: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e40: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5e50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
5e60: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
5e70: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
5e80: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5e90: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5ea0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
5eb0: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
5ec0: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
5ed0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
5ee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
5ef0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
5f00: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* 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 41 55 54 4f 50  QLITE_OPEN_AUTOP
5f30: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
5f40: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* 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 55 52 49 20 20  QLITE_OPEN_URI  
5f70: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f80: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
5f90: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5fa0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
5fb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
5fc0: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
5fd0: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
5fe0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
5ff0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6000: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
6010: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6020: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
6030: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
6040: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6050: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
6060: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* 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 52 41 4e 53  QLITE_OPEN_TRANS
6090: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
60a0: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* 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 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
60d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
60e0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* 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 54 45 4d 50 5f  QLITE_OPEN_TEMP_
6110: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
6120: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* 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 53 55 42 4a 4f  QLITE_OPEN_SUBJO
6150: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
6160: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* 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 4d 41 53 54 45  QLITE_OPEN_MASTE
6190: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
61a0: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* 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 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
61d0: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
61e0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
61f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6200: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6210: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
6220: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
6230: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
6240: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
6250: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6260: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
6270: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
6280: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
6290: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62a0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
62b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
62c0: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
62d0: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
62e0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
62f0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
6300: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6320: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
6330: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
6340: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6360: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
6370: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
6380: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
6390: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
63a0: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
63b0: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
63c0: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
63d0: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
63e0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
63f0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
6400: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
6410: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
6420: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
6430: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
6440: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
6450: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
6460: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
6470: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
6480: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
6490: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
64a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
64b0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
64c0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
64d0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
64e0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6500: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
6510: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
6520: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
6530: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
6540: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
6550: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
6560: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
6570: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
6580: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
6590: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
65a0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
65b0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
65c0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
65d0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
65e0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
65f0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
6600: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
6610: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
6620: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
6630: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
6640: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
6650: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
6660: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
6670: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
6680: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
6690: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
66a0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
66b0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
66c0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
66d0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
66e0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
66f0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
6700: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
6710: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
6720: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
6730: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
6740: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
6750: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
6760: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
6770: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
6780: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
6790: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
67a0: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
67b0: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
67c0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
67d0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
67e0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
67f0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
6800: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
6810: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
6820: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
6830: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
6840: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
6850: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
6860: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
6870: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
6880: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
6890: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
68a0: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
68b0: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
68c0: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
68d0: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
68e0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
68f0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
6900: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6910: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6930: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
6940: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
6950: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
6960: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
6970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6980: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
6990: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
69a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
69d0: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
69e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
69f0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6a00: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6a10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a20: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6a30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a40: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
6a50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6a60: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
6a70: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
6a80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6a90: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6aa0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6ab0: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6ac0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6ad0: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6ae0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6af0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b00: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6b10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6b20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b30: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6b40: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
6b50: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
6b60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
6b70: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
6b80: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
6b90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6ba0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6bb0: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6bc0: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
6bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
6be0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
6bf0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
6c00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
6c10: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
6c20: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
6c30: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
6c40: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6c50: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
6c60: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
6c70: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
6c80: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
6c90: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
6ca0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
6cb0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
6cc0: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
6cd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
6ce0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
6cf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6d00: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
6d10: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
6d20: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
6d30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
6d40: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
6d50: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
6d60: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
6d70: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
6d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d90: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
6da0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
6db0: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
6dc0: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
6dd0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
6de0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
6df0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
6e00: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
6e10: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
6e20: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
6e30: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
6e40: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
6e50: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e60: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
6e70: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
6e80: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
6e90: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
6ea0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
6eb0: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
6ec0: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
6ed0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
6ee0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
6ef0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
6f00: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
6f10: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
6f20: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
6f30: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
6f40: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
6f50: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
6f60: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
6f70: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
6f80: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
6f90: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
6fa0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
6fb0: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
6fc0: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
6fd0: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
6fe0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
6ff0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
7000: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7010: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
7020: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
7030: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
7040: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
7050: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
7060: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
7070: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
7080: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
7090: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
70a0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
70b0: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
70c0: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
70d0: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
70e0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
70f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
7100: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
7110: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
7120: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
7130: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
7140: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
7150: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
7160: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
7170: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
7180: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
7190: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
71a0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
71b0: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
71c0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
71d0: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
71e0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
71f0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
7200: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
7210: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
7220: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
7230: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
7240: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
7250: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
7260: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
7270: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
7280: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
7290: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
72a0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
72b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
72c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
72d0: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
72e0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
72f0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
7300: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
7310: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
7320: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
7330: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
7340: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
7350: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7360: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
7370: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
7380: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
7390: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
73a0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
73b0: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
73c0: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
73d0: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
73e0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
73f0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
7400: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
7410: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
7420: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
7430: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
7440: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
7450: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
7460: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
7470: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
7480: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
7490: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
74a0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
74b0: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
74c0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
74d0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
74e0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
74f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
7500: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
7510: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7520: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
7530: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
7540: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
7550: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7560: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
7570: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
7580: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
7590: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
75a0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
75b0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
75c0: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
75d0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
75e0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
75f0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
7600: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
7610: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
7620: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
7630: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
7640: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
7650: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
7660: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
7670: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
7680: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
7690: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
76a0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
76b0: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
76c0: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
76d0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
76e0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
76f0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7700: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
7710: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
7720: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
7730: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
7740: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
7750: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
7760: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
7770: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
7780: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
7790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
77a0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
77b0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
77c0: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
77d0: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
77e0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
77f0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
7800: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
7810: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
7820: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7830: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
7840: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
7850: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
7860: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
7870: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
7880: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
7890: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
78a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
78b0: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
78c0: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
78d0: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
78e0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
78f0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
7900: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
7910: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
7920: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
7930: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
7940: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
7950: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
7960: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
7970: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
7980: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
7990: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
79a0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
79b0: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
79c0: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
79d0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
79e0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
79f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
7a00: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
7a10: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a20: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
7a30: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a40: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
7a50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7a60: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
7a70: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7a80: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
7a90: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
7aa0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
7ab0: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
7ac0: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
7ad0: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
7ae0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
7af0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
7b00: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
7b10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
7b20: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
7b30: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
7b40: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
7b50: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
7b60: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
7b70: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
7b80: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
7b90: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
7ba0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
7bb0: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
7bc0: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
7bd0: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
7be0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
7bf0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
7c00: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
7c10: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
7c20: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
7c30: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
7c40: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
7c50: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
7c60: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
7c70: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
7c80: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
7c90: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
7ca0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
7cb0: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
7cc0: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
7cd0: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
7ce0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
7cf0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
7d00: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
7d10: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
7d20: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
7d30: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
7d40: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
7d50: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
7d60: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
7d70: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
7d80: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
7d90: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
7da0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
7db0: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
7dc0: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
7dd0: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
7de0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
7df0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
7e00: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
7e10: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
7e20: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
7e30: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
7e40: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
7e50: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
7e60: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
7e70: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
7e80: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
7e90: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
7ea0: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7eb0: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7ec0: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7ed0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7ee0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7ef0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7f00: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7f10: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7f20: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7f30: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7f40: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
7f50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
7f60: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
7f70: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
7f80: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7f90: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7fa0: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7fb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
7fc0: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7fd0: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7fe0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7ff0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
8000: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
8010: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
8020: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
8030: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
8040: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8050: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8060: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8070: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8080: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8090: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
80a0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
80b0: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
80c0: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
80d0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
80e0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
80f0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8100: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8110: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
8120: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
8130: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
8140: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8150: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8160: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8170: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8180: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8190: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
81a0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81b0: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
81c0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
81d0: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
81e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81f0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
8200: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8210: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
8220: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
8230: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
8240: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8250: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8260: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8270: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8280: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8290: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
82a0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
82b0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
82c0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
82d0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
82e0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
82f0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8300: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8310: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8320: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8330: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8340: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8350: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8360: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8380: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8390: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
83a0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
83b0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
83c0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
83d0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
83e0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
83f0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8400: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8410: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8420: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8430: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8440: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8450: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8460: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8470: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8480: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8490: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
84a0: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
84b0: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
84c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
84d0: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
84e0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
84f0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
8500: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
8510: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
8520: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
8530: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
8540: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8550: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8560: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8570: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8580: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8590: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
85a0: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
85b0: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
85c0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
85d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
85e0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
85f0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
8600: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8610: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
8620: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
8630: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8640: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8650: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8660: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8670: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8680: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8690: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
86a0: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
86b0: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
86c0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
86d0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
86e0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
86f0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8700: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
8710: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
8720: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
8730: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
8740: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8760: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8770: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8780: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8790: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
87a0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
87b0: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
87c0: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
87d0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
87e0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
87f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
8800: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
8810: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
8820: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
8830: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
8840: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8850: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8860: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8870: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8880: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8890: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
88a0: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
88b0: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
88c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
88d0: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
88e0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
88f0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
8900: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
8910: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
8920: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
8930: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
8940: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8950: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8970: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8980: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8990: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
89a0: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
89b0: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
89c0: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
89d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
89e0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
89f0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8a00: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8a10: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8a20: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8a30: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8a40: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8a50: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8a60: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8a70: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8a80: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8a90: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8aa0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8ab0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8ac0: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8ad0: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8ae0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
8af0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
8b00: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
8b10: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
8b20: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
8b30: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
8b40: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
8b50: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8b60: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
8b70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8b80: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
8b90: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
8ba0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
8bb0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
8bc0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
8bd0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
8be0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
8bf0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8c00: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
8c10: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
8c20: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
8c30: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
8c40: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
8c50: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
8c60: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
8c70: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
8c80: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
8c90: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
8ca0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
8cb0: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
8cc0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
8cd0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
8ce0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
8cf0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
8d00: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
8d10: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
8d20: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
8d30: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
8d40: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
8d50: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
8d60: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
8d70: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
8d80: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
8d90: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
8da0: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
8db0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8dc0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8dd0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8de0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8df0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8e00: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8e10: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8e20: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8e30: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8e40: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8e50: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8e60: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8e70: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8e80: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8e90: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8ea0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8eb0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8ec0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8ed0: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8ee0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8ef0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8f00: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8f10: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8f20: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8f30: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8f40: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8f50: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8f60: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8f70: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8f80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8f90: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8fa0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8fb0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8fc0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8fd0: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8fe0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8ff0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
9000: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
9010: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
9020: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
9030: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
9040: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
9050: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
9060: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
9070: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
9080: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
9090: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
90a0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
90b0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
90c0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
90d0: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
90e0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
90f0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
9100: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
9110: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
9120: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
9130: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
9140: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
9150: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
9160: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
9170: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
9180: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9190: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
91a0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
91b0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
91c0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
91d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
91e0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
91f0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9200: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9210: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9220: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9230: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9240: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9250: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9260: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
9270: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9280: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
9290: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
92a0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
92b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
92c0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
92d0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
92e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
92f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9300: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9310: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9320: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9330: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9340: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9350: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9360: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
9370: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
9390: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
93a0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
93b0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
93c0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
93d0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
93e0: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
93f0: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9400: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9410: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9420: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9430: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9440: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9450: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9460: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
9470: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
9480: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
9490: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
94a0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
94b0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
94c0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
94d0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
94e0: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
94f0: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9500: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9510: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9520: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9530: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9540: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9550: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9560: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
9570: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
9580: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
9590: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
95a0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
95b0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
95c0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
95d0: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
95e0: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
95f0: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9600: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9610: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9620: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9630: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9640: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9650: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9660: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
9670: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
9680: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9690: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
96a0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
96b0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
96c0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
96d0: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
96e0: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
96f0: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9700: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9710: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9720: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9730: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9740: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9750: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9760: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
9770: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
9780: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9790: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
97a0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
97b0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
97c0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
97d0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
97e0: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
97f0: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9800: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9810: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9820: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9840: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9850: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9860: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
9870: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
9880: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
9890: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
98a0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
98b0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
98c0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
98d0: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
98e0: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
98f0: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9900: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9910: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9920: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9930: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9940: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9950: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9960: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
9970: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
9980: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
9990: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
99a0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
99b0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
99c0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
99d0: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
99e0: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
99f0: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9a00: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9a10: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9a20: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9a30: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9a40: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9a50: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9a60: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
9a70: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
9a80: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
9a90: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
9aa0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9ab0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
9ac0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9ad0: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9ae0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9af0: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9b00: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9b10: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9b20: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9b30: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9b40: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9b50: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9b60: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
9b70: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
9b80: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
9b90: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
9ba0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
9bb0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
9bc0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9bd0: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9be0: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9bf0: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9c00: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9c10: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9c20: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9c30: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9c40: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9c50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9c60: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9c70: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9c80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9c90: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ca0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9cb0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9cc0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9cd0: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9ce0: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9cf0: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9d00: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9d10: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9d20: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9d30: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9d40: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9d50: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9d60: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9d70: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9d80: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9d90: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9da0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9db0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9dc0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9dd0: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9de0: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9df0: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9e00: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9e10: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9e20: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9e30: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9e40: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9e50: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9e60: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9e70: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9e80: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9e90: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9ea0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9eb0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9ec0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9ed0: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9ee0: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9ef0: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9f00: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9f10: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9f20: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9f30: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9f40: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9f50: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9f60: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9f70: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9f80: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9f90: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9fa0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9fb0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9fc0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9fd0: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9fe0: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9ff0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
a000: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
a010: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a020: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a030: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
a040: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a050: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
a060: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
a070: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
a080: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a090: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
a0a0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
a0b0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
a0c0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
a0d0: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
a0e0: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
a0f0: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
a100: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
a110: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
a120: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a130: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
a140: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
a150: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a160: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
a170: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
a180: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
a190: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
a1a0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
a1b0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
a1c0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a1d0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a1e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a1f0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a200: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a210: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a220: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a230: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a240: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a250: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a260: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a270: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a280: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a290: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a2a0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a2b0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a2c0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a2d0: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a2e0: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a2f0: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a300: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a310: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a320: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a330: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a340: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a350: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a360: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a370: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a380: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a390: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a3a0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a3b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a3c0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a3d0: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a3e0: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a3f0: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a400: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a410: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a420: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a430: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a440: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a450: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a460: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a470: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a480: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a490: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a4a0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a4b0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a4c0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a4d0: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a4e0: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a4f0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a500: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a510: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a520: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a530: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a540: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a550: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a560: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a570: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a580: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a590: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a5a0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a5b0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a5c0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a5d0: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a5e0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a5f0: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a600: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a610: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a620: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a630: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a640: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a650: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a660: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a670: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a680: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a690: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a6a0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a6b0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a6c0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a6d0: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a6e0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a6f0: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a700: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a710: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a720: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a730: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a740: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a750: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a760: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a770: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a780: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a790: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a7a0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a7b0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a7c0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a7d0: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a7e0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a7f0: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a800: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a810: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a820: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a830: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a840: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a850: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a860: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a870: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a880: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a890: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a8a0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a8b0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a8c0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a8d0: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a8e0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a8f0: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a900: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a910: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a920: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a930: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a940: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a950: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a960: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a970: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a980: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a990: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a9a0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a9b0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a9c0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a9d0: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a9e0: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a9f0: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
aa00: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
aa10: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
aa20: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
aa30: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
aa40: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
aa50: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
aa60: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
aa70: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
aa80: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
aa90: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
aaa0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
aab0: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
aac0: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
aad0: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
aae0: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
aaf0: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
ab00: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
ab10: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
ab20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab30: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab40: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab50: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab60: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab70: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab80: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab90: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
aba0: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
abb0: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
abc0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
abd0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
abe0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abf0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
ac00: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
ac10: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac30: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac40: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac50: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac60: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac70: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac80: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac90: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
aca0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
acb0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
acc0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
acd0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
ace0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acf0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ad00: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
ad10: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad20: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad30: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad40: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad50: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad60: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad70: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad80: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad90: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ada0: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
adb0: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
adc0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
add0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ade0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
adf0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ae00: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ae10: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae20: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae30: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae40: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae50: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae60: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae70: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae80: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae90: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
aea0: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
aeb0: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
aec0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
aed0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aee0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aef0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
af00: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
af10: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af20: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af30: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af40: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af50: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af60: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af80: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af90: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
afa0: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
afb0: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
afc0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
afd0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afe0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
aff0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
b000: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
b010: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b020: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b030: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b040: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b050: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b060: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b070: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b080: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b090: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b0a0: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b0b0: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b0c0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b0d0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0e0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0f0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b100: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b110: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b120: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b130: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b140: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b150: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b160: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b170: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b180: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b190: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b1a0: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b1b0: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b1c0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b1d0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1e0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1f0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b200: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b210: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b220: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b230: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b240: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b250: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b260: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b270: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b280: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b290: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b2a0: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b2b0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b2c0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b2d0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2e0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2f0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b300: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b310: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b320: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b330: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b340: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b350: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b360: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b370: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b380: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b390: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b3a0: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b3b0: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b3c0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3d0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3e0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3f0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b400: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b410: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b420: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b430: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b440: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b450: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b460: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b470: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b480: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b490: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b4a0: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b4b0: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b4c0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b4d0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4e0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4f0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b500: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b510: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b520: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b530: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b540: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b550: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b560: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b570: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b580: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b590: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b5a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b5b0: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b5c0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b5d0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5e0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5f0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b600: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b610: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b620: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b630: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b640: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b650: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b660: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b670: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b680: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b690: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b6a0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b6b0: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b6c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b6d0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6e0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b6f0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b700: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b710: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b720: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b730: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b740: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b750: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b760: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b770: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b780: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b790: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b7a0: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b7b0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b7c0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b7d0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b7e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b7f0: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
b800: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
b810: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
b820: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
b830: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
b840: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
b850: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
b860: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
b870: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
b880: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
b890: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
b8a0: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
b8b0: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
b8c0: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
b8d0: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
b8e0: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
b8f0: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
b900: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
b910: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
b920: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
b930: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
b940: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
b950: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
b960: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b970: 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d  TE_FCNTL_ZIPVFS]
b980: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b990: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f  _FCNTL_ZIPVFS] o
b9a0: 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65  pcode is impleme
b9b0: 6e 74 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f  nted by zipvfs o
b9c0: 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a  nly. All other.*
b9d0: 2a 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74  * VFS should ret
b9e0: 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  urn SQLITE_NOTFO
b9f0: 55 4e 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63  UND for this opc
ba00: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ode..**.** <li>[
ba10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42  [SQLITE_FCNTL_RB
ba20: 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  U]].** The [SQLI
ba30: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70  TE_FCNTL_RBU] op
ba40: 63 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  code is implemen
ba50: 74 65 64 20 62 79 20 74 68 65 20 73 70 65 63 69  ted by the speci
ba60: 61 6c 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a  al VFS used by.*
ba70: 2a 20 74 68 65 20 52 42 55 20 65 78 74 65 6e 73  * the RBU extens
ba80: 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f  ion only.  All o
ba90: 74 68 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20  ther VFS should 
baa0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
bab0: 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68  TFOUND for.** th
bac0: 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20  is opcode.  .** 
bad0: 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65  </ul>.*/.#define
bae0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f   SQLITE_FCNTL_LO
baf0: 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20 20  CKSTATE         
bb00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54  SQLITE_FCNTL_GET
bb20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
bb30: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
bb40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f  QLITE_FCNTL_SET_
bb50: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bb60: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
bb70: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
bb80: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
bb90: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
bba0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
bbb0: 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 20  INT             
bbc0: 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
bbd0: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
bbe0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  IZE             
bbf0: 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
bc00: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
bc10: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
bc20: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
bc30: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54  _FCNTL_SYNC_OMIT
bc40: 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20 38  TED            8
bc50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc60: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
bc70: 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39 0a  ETRY          9.
bc80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bc90: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
bca0: 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
bcb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bcc0: 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20  NTL_OVERWRITE   
bcd0: 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23 64             11.#d
bce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bcf0: 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20  TL_VFSNAME      
bd00: 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64 65            12.#de
bd10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bd20: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
bd30: 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65 66  WRITE    13.#def
bd40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bd50: 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
bd60: 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66 69          14.#defi
bd70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bd80: 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20  BUSYHANDLER     
bd90: 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e         15.#defin
bda0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
bdb0: 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20  EMPFILENAME     
bdc0: 20 20 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65        16.#define
bdd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d   SQLITE_FCNTL_MM
bde0: 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  AP_SIZE         
bdf0: 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20       18.#define 
be00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
be10: 43 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CE              
be20: 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53      19.#define S
be30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
be40: 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20 20 20  MOVED           
be50: 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51     20.#define SQ
be60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20  LITE_FCNTL_SYNC 
be70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
be80: 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    21.#define SQL
be90: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
bea0: 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20 20 20  _PHASETWO       
beb0: 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   22.#define SQLI
bec0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53  TE_FCNTL_WIN32_S
bed0: 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20  ET_HANDLE       
bee0: 32 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  23.#define SQLIT
bef0: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
bf00: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  K              2
bf10: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
bf20: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20  _FCNTL_ZIPVFS   
bf30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
bf40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bf50: 46 43 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20  FCNTL_RBU       
bf60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 36 0a               26.
bf70: 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e  ./* deprecated n
bf80: 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ames */.#define 
bf90: 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50  SQLITE_GET_LOCKP
bfa0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51  ROXYFILE      SQ
bfb0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
bfc0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65  OCKPROXYFILE.#de
bfd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f  fine SQLITE_SET_
bfe0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
bff0: 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f     SQLITE_FCNTL_
c000: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c010: 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  E.#define SQLITE
c020: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
c030: 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46          SQLITE_F
c040: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a  CNTL_LAST_ERRNO.
c050: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c060: 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a  : Mutex Handle.*
c070: 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d  *.** The mutex m
c080: 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c  odule within SQL
c090: 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c  ite defines [sql
c0a0: 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62  ite3_mutex] to b
c0b0: 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74  e an.** abstract
c0c0: 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65   type for a mute
c0d0: 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53  x object.  The S
c0e0: 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72  QLite core never
c0f0: 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65   looks.** at the
c100: 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
c110: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b  entation of an [
c120: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20  sqlite3_mutex]. 
c130: 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c   It only.** deal
c140: 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20  s with pointers 
c150: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
c160: 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a  mutex] object..*
c170: 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65  *.** Mutexes are
c180: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c190: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c  sqlite3_mutex_al
c1a0: 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  loc()]..*/.typed
c1b0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c1c0: 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f  3_mutex sqlite3_
c1d0: 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  mutex;../*.** CA
c1e0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
c1f0: 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  face Object.**.*
c200: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
c210: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c220: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
c230: 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65  the interface be
c240: 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c  tween.** the SQL
c250: 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65  ite core and the
c260: 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72   underlying oper
c270: 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54  ating system.  T
c280: 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74  he "vfs".** in t
c290: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f  he name of the o
c2a0: 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72  bject stands for
c2b0: 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73   "virtual file s
c2c0: 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20  ystem".  See.** 
c2d0: 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64  the [VFS | VFS d
c2e0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
c2f0: 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d  r further inform
c300: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
c310: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56   value of the iV
c320: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20  ersion field is 
c330: 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20  initially 1 but 
c340: 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e  may be larger in
c350: 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69  .** future versi
c360: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20  ons of SQLite.  
c370: 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  Additional field
c380: 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65  s may be appende
c390: 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a  d to this.** obj
c3a0: 65 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65  ect when the iVe
c3b0: 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69  rsion value is i
c3c0: 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20  ncreased.  Note 
c3d0: 74 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75  that the structu
c3e0: 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c  re.** of the sql
c3f0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
c400: 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74  changes in the t
c410: 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65  ransaction betwe
c420: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  en.** SQLite ver
c430: 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33  sion 3.5.9 and 3
c440: 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65  .6.0 and yet the
c450: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
c460: 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66  was not.** modif
c470: 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ied..**.** The s
c480: 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73  zOsFile field is
c490: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
c4a0: 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c   subclassed [sql
c4b0: 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74  ite3_file].** st
c4c0: 72 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20  ructure used by 
c4d0: 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74  this VFS.  mxPat
c4e0: 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78  hname is the max
c4f0: 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a  imum length of.*
c500: 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20  * a pathname in 
c510: 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20  this VFS..**.** 
c520: 52 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74  Registered sqlit
c530: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61  e3_vfs objects a
c540: 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e  re kept on a lin
c550: 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20  ked list formed 
c560: 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20  by.** the pNext 
c570: 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73  pointer.  The [s
c580: 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73  qlite3_vfs_regis
c590: 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ter()].** and [s
c5a0: 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67  qlite3_vfs_unreg
c5b0: 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61  ister()] interfa
c5c0: 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20  ces manage this 
c5d0: 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72  list.** in a thr
c5e0: 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54  ead-safe way.  T
c5f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f  he [sqlite3_vfs_
c600: 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63  find()] interfac
c610: 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68  e.** searches th
c620: 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72  e list.  Neither
c630: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c640: 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46   code nor the VF
c650: 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  S.** implementat
c660: 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ion should use t
c670: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
c680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78  ..**.** The pNex
c690: 74 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f  t field is the o
c6a0: 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65  nly field in the
c6b0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c6c0: 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53  structure that S
c6d0: 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20  QLite will ever 
c6e0: 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20  modify.  SQLite 
c6f0: 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73  will only access
c700: 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  .** or modify th
c710: 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68  is field while h
c720: 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75  olding a particu
c730: 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78  lar static mutex
c740: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
c750: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65  tion should neve
c760: 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e  r modify anythin
c770: 67 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c  g within the sql
c780: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65  ite3_vfs.** obje
c790: 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65  ct once the obje
c7a0: 63 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69  ct has been regi
c7b0: 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  stered..**.** Th
c7c0: 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f  e zName field ho
c7d0: 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  lds the name of 
c7e0: 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20  the VFS module. 
c7f0: 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a   The name must.*
c800: 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f  * be unique acro
c810: 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c  ss all VFS modul
c820: 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  es..**.** [[sqli
c830: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a  te3_vfs.xOpen]].
c840: 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
c850: 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a  ntees that the z
c860: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c870: 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69  er to xOpen.** i
c880: 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20  s either a NULL 
c890: 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e  pointer or strin
c8a0: 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  g obtained.** fr
c8b0: 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  om xFullPathname
c8c0: 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f  () with an optio
c8d0: 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64  nal suffix added
c8e0: 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69  ..** ^If a suffi
c8f0: 78 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68  x is added to th
c900: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
c910: 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a  meter, it will.*
c920: 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73  * consist of a s
c930: 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63  ingle "-" charac
c940: 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  ter followed by 
c950: 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20  no more than.** 
c960: 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  11 alphanumeric 
c970: 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61  and/or "-" chara
c980: 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  cters..** ^SQLit
c990: 65 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e  e further guaran
c9a0: 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  tees that.** the
c9b0: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20   string will be 
c9c0: 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e  valid and unchan
c9d0: 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65  ged until xClose
c9e0: 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e  () is.** called.
c9f0: 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
ca00: 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
ca10: 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  e,.** the [sqlit
ca20: 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66  e3_file] can saf
ca30: 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e  ely store a poin
ca40: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69  ter to the.** fi
ca50: 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65  lename if it nee
ca60: 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74  ds to remember t
ca70: 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20  he filename for 
ca80: 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20  some reason..** 
ca90: 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
caa0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
cab0: 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  pen is a NULL po
cac0: 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e  inter then xOpen
cad0: 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20  .** must invent 
cae0: 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72  its own temporar
caf0: 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66  y name for the f
cb00: 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20  ile.  ^Whenever 
cb10: 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d  the .** xFilenam
cb20: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e  e parameter is N
cb30: 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f  ULL it will also
cb40: 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
cb50: 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70  t the.** flags p
cb60: 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e  arameter will in
cb70: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
cb80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cb90: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61  ]..**.** The fla
cba0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  gs argument to x
cbb0: 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20  Open() includes 
cbc0: 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a  all bits set in.
cbd0: 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  ** the flags arg
cbe0: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
cbf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f  3_open_v2()].  O
cc00: 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r if [sqlite3_op
cc10: 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  en()].** or [sql
cc20: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69  ite3_open16()] i
cc30: 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61  s used, then fla
cc40: 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c  gs includes at l
cc50: 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  east.** [SQLITE_
cc60: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20  OPEN_READWRITE] 
cc70: 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  | [SQLITE_OPEN_C
cc80: 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78  REATE]. .** If x
cc90: 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66  Open() opens a f
cca0: 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68  ile read-only th
ccb0: 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74  en it sets *pOut
ccc0: 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c  Flags to.** incl
ccd0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
cce0: 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68  _READONLY].  Oth
ccf0: 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74  er bits in *pOut
cd00: 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74  Flags may be set
cd10: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65  ..**.** ^(SQLite
cd20: 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f   will also add o
cd30: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
cd40: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
cd50: 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c   xOpen().** call
cd60: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
cd70: 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20  he object being 
cd80: 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  opened:.**.** <u
cd90: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  l>.** <li>  [SQL
cda0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
cdb0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
cdc0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
cdd0: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
cde0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
cdf0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ce00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
ce10: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
ce20: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ce30: 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20  RANSIENT_DB].** 
ce40: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ce50: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a  EN_SUBJOURNAL].*
ce60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ce70: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
ce80: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ce90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a  QLITE_OPEN_WAL].
cea0: 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
ceb0: 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d   The file I/O im
cec0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e  plementation can
ced0: 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20   use the object 
cee0: 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a  type flags to.**
cef0: 20 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20   change the way 
cf00: 69 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69  it deals with fi
cf10: 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  les.  For exampl
cf20: 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  e, an applicatio
cf30: 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e  n.** that does n
cf40: 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72  ot care about cr
cf50: 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20  ash recovery or 
cf60: 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d  rollback might m
cf70: 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20  ake.** the open 
cf80: 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c  of a journal fil
cf90: 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74  e a no-op.  Writ
cfa0: 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e  es to this journ
cfb0: 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f  al would.** also
cfc0: 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20   be no-ops, and 
cfd0: 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72  any attempt to r
cfe0: 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20  ead the journal 
cff0: 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20  would return.** 
d000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f  SQLITE_IOERR.  O
d010: 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  r the implementa
d020: 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67  tion might recog
d030: 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61  nize that a data
d040: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c  base.** file wil
d050: 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d  l be doing page-
d060: 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72  aligned sector r
d070: 65 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20  eads and writes 
d080: 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f  in a random.** o
d090: 72 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20  rder and set up 
d0a0: 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65  its I/O subsyste
d0b0: 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a  m accordingly..*
d0c0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68  *.** SQLite migh
d0d0: 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  t also add one o
d0e0: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
d0f0: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
d100: 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a  en method:.**.**
d110: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
d120: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
d130: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69  EONCLOSE].** <li
d140: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  > [SQLITE_OPEN_E
d150: 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75  XCLUSIVE].** </u
d160: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  l>.**.** The [SQ
d170: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
d180: 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65  ONCLOSE] flag me
d190: 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ans the file sho
d1a0: 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65  uld be.** delete
d1b0: 64 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f  d when it is clo
d1c0: 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  sed.  ^The [SQLI
d1d0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
d1e0: 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62  CLOSE].** will b
d1f0: 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64  e set for TEMP d
d200: 61 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65  atabases and the
d210: 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61  ir journals, tra
d220: 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61  nsient.** databa
d230: 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72  ses, and subjour
d240: 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nals..**.** ^The
d250: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
d260: 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73  CLUSIVE] flag is
d270: 20 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20   always used in 
d280: 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  conjunction.** w
d290: 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
d2a0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61  OPEN_CREATE] fla
d2b0: 67 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74  g, which are bot
d2c0: 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e  h directly.** an
d2d0: 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f  alogous to the O
d2e0: 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41  _EXCL and O_CREA
d2f0: 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50  T flags of the P
d300: 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41  OSIX open().** A
d310: 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  PI.  The SQLITE_
d320: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66  OPEN_EXCLUSIVE f
d330: 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64  lag, when paired
d340: 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51   with the .** SQ
d350: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d360: 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64  , is used to ind
d370: 69 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20  icate that file 
d380: 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a  should always.**
d390: 20 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64   be created, and
d3a0: 20 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65   that it is an e
d3b0: 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61  rror if it alrea
d3c0: 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74  dy exists..** It
d3d0: 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75   is <i>not</i> u
d3e0: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
d3f0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
d400: 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f  be opened .** fo
d410: 72 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65  r exclusive acce
d420: 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65  ss..**.** ^At le
d430: 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74  ast szOsFile byt
d440: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65  es of memory are
d450: 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51   allocated by SQ
d460: 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20  Lite.** to hold 
d470: 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69  the  [sqlite3_fi
d480: 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61  le] structure pa
d490: 73 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72  ssed as the thir
d4a0: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
d4b0: 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70   xOpen.  The xOp
d4c0: 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e  en method does n
d4d0: 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c  ot have to.** al
d4e0: 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63  locate the struc
d4f0: 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20  ture; it should 
d500: 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e  just fill it in.
d510: 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74    Note that.** t
d520: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
d530: 6d 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c  must set the sql
d540: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
d550: 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20  ds to either.** 
d560: 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33  a valid [sqlite3
d570: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
d580: 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20  ect or to NULL. 
d590: 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a   xOpen must do.*
d5a0: 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74  * this even if t
d5b0: 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20  he open fails.  
d5c0: 53 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74  SQLite expects t
d5d0: 68 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hat the sqlite3_
d5e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a  file.pMethods.**
d5f0: 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65   element will be
d600: 20 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70   valid after xOp
d610: 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72  en returns regar
d620: 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63  dless of the suc
d630: 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75  cess.** or failu
d640: 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20  re of the xOpen 
d650: 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  call..**.** [[sq
d660: 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73  lite3_vfs.xAcces
d670: 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67  s]].** ^The flag
d680: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41  s argument to xA
d690: 63 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b  ccess() may be [
d6a0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d6b0: 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  ISTS].** to test
d6c0: 20 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e   for the existen
d6d0: 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72  ce of a file, or
d6e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d6f0: 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a  READWRITE] to.**
d700: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d710: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
d720: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f   and writable, o
d730: 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53  r [SQLITE_ACCESS
d740: 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73  _READ].** to tes
d750: 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
d760: 20 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61   is at least rea
d770: 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c  dable.   The fil
d780: 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69  e can be a.** di
d790: 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e  rectory..**.** ^
d7a0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61  SQLite will alwa
d7b0: 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c  ys allocate at l
d7c0: 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b  east mxPathname+
d7d0: 31 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a  1 bytes for the.
d7e0: 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  ** output buffer
d7f0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20   xFullPathname. 
d800: 20 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20   The exact size 
d810: 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  of the output bu
d820: 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20  ffer.** is also 
d830: 70 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61  passed as a para
d840: 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d  meter to both  m
d850: 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f  ethods. If the o
d860: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d870: 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f  is not large eno
d880: 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e  ugh, [SQLITE_CAN
d890: 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65  TOPEN] should be
d8a0: 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65   returned. Since
d8b0: 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64   this is.** hand
d8c0: 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65  led as a fatal e
d8d0: 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20  rror by SQLite, 
d8e0: 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  vfs implementati
d8f0: 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61  ons should endea
d900: 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e  vor.** to preven
d910: 74 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e  t this by settin
d920: 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20  g mxPathname to 
d930: 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c  a sufficiently l
d940: 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a  arge value..**.*
d950: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d960: 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78  s(), xSleep(), x
d970: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61  CurrentTime(), a
d980: 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  nd xCurrentTimeI
d990: 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66  nt64().** interf
d9a0: 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72  aces are not str
d9b0: 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20  ictly a part of 
d9c0: 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20  the filesystem, 
d9d0: 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  but they are.** 
d9e0: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
d9f0: 56 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f  VFS structure fo
da00: 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a  r completeness..
da10: 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65  ** The xRandomne
da20: 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74  ss() function at
da30: 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e  tempts to return
da40: 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a   nBytes bytes.**
da50: 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79   of good-quality
da60: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
da70: 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75   zOut.  The retu
da80: 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74  rn value is.** t
da90: 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72  he actual number
daa0: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e   of bytes of ran
dab0: 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
dac0: 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28  ..** The xSleep(
dad0: 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20  ) method causes 
dae0: 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65  the calling thre
daf0: 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20  ad to sleep for 
db00: 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20  at.** least the 
db10: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73  number of micros
db20: 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e  econds given.  ^
db30: 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  The xCurrentTime
db40: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
db50: 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61  urns a Julian Da
db60: 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65  y Number for the
db70: 20 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e   current date an
db80: 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66  d time as.** a f
db90: 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
dba0: 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75  lue..** ^The xCu
dbb0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dbc0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c   method returns,
dbd0: 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20   as an integer, 
dbe0: 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61  the Julian.** Da
dbf0: 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c  y Number multipl
dc00: 69 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20  ied by 86400000 
dc10: 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d  (the number of m
dc20: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a  illiseconds in .
dc30: 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79  ** a 24-hour day
dc40: 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ).  .** ^SQLite 
dc50: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75  will use the xCu
dc60: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29  rrentTimeInt64()
dc70: 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74   method to get t
dc80: 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61  he current.** da
dc90: 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74  te and time if t
dca0: 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76  hat method is av
dcb0: 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72  ailable (if iVer
dcc0: 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a  sion is 2 or .**
dcd0: 20 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65   greater and the
dce0: 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65   function pointe
dcf0: 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61  r is not NULL) a
dd00: 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63  nd will fall bac
dd10: 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74  k.** to xCurrent
dd20: 54 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65  Time() if xCurre
dd30: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73  ntTimeInt64() is
dd40: 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
dd50: 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73  .** ^The xSetSys
dd60: 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53  temCall(), xGetS
dd70: 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64  ystemCall(), and
dd80: 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c   xNestSystemCall
dd90: 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
dda0: 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79   are not used by
ddb0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
ddc0: 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61  .  These optiona
ddd0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
dde0: 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20   provided.** by 
ddf0: 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61  some VFSes to fa
de00: 63 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67  cilitate testing
de10: 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65   of the VFS code
de20: 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20  . By overriding 
de30: 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73  .** system calls
de40: 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20   with functions 
de50: 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f  under its contro
de60: 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61  l, a test progra
de70: 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74  m can.** simulat
de80: 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72  e faults and err
de90: 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68  or conditions th
dea0: 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69  at would otherwi
deb0: 73 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a  se be difficult.
dec0: 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65  ** or impossible
ded0: 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65   to induce.  The
dee0: 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63   set of system c
def0: 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65  alls that can be
df00: 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76   overridden.** v
df10: 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56  aries from one V
df20: 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61  FS to another, a
df30: 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73  nd from one vers
df40: 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ion of the same 
df50: 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65  VFS to the.** ne
df60: 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  xt.  Application
df70: 73 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65  s that use these
df80: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74   interfaces must
df90: 20 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72   be prepared for
dfa0: 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f   any.** or all o
dfb0: 66 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  f these interfac
dfc0: 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72  es to be NULL or
dfd0: 20 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76   for their behav
dfe0: 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a  ior to change.**
dff0: 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73   from one releas
e000: 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20  e to the next.  
e010: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73  Applications mus
e020: 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f  t not attempt to
e030: 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f   access.** any o
e040: 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20  f these methods 
e050: 69 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  if the iVersion 
e060: 6f 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65  of the VFS is le
e070: 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79  ss than 3..*/.ty
e080: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
e090: 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33  ite3_vfs sqlite3
e0a0: 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f  _vfs;.typedef vo
e0b0: 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73  id (*sqlite3_sys
e0c0: 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b  call_ptr)(void);
e0d0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
e0e0: 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  vfs {.  int iVer
e0f0: 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20  sion;           
e100: 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65   /* Structure ve
e110: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75  rsion number (cu
e120: 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20  rrently 3) */.  
e130: 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20  int szOsFile;   
e140: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65           /* Size
e150: 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73   of subclassed s
e160: 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20  qlite3_file */. 
e170: 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b   int mxPathname;
e180: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
e190: 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61  imum file pathna
e1a0: 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73  me length */.  s
e1b0: 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78  qlite3_vfs *pNex
e1c0: 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20  t;      /* Next 
e1d0: 72 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a  registered VFS *
e1e0: 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
e1f0: 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20  zName;       /* 
e200: 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72  Name of this vir
e210: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
e220: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
e230: 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f  Data;          /
e240: 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70  * Pointer to app
e250: 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69  lication-specifi
e260: 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20  c data */.  int 
e270: 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33  (*xOpen)(sqlite3
e280: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e290: 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65  r *zName, sqlite
e2a0: 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20  3_file*,.       
e2b0: 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67          int flag
e2c0: 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67  s, int *pOutFlag
e2d0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c  s);.  int (*xDel
e2e0: 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ete)(sqlite3_vfs
e2f0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e300: 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69  Name, int syncDi
e310: 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63  r);.  int (*xAcc
e320: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
e330: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e340: 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c  Name, int flags,
e350: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
e360: 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74    int (*xFullPat
e370: 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  hname)(sqlite3_v
e380: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
e390: 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74  *zName, int nOut
e3a0: 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20  , char *zOut);. 
e3b0: 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e   void *(*xDlOpen
e3c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e3d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
e3e0: 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28  ename);.  void (
e3f0: 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74  *xDlError)(sqlit
e400: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79  e3_vfs*, int nBy
e410: 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73  te, char *zErrMs
e420: 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78  g);.  void (*(*x
e430: 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76  DlSym)(sqlite3_v
e440: 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74  fs*,void*, const
e450: 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29   char *zSymbol))
e460: 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28  (void);.  void (
e470: 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74  *xDlClose)(sqlit
e480: 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b  e3_vfs*, void*);
e490: 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d  .  int (*xRandom
e4a0: 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66  ness)(sqlite3_vf
e4b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
e4c0: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e  har *zOut);.  in
e4d0: 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69  t (*xSleep)(sqli
e4e0: 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69  te3_vfs*, int mi
e4f0: 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69  croseconds);.  i
e500: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e510: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e520: 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74   double*);.  int
e530: 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72   (*xGetLastError
e540: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e550: 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20  int, char *);.  
e560: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e570: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e580: 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68   version 1 of th
e590: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e5a0: 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74  ect.  ** definit
e5b0: 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74  ion.  Those that
e5c0: 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65   follow are adde
e5d0: 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f  d in version 2 o
e5e0: 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69  r later.  */.  i
e5f0: 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d  nt (*xCurrentTim
e600: 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f  eInt64)(sqlite3_
e610: 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  vfs*, sqlite3_in
e620: 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  t64*);.  /*.  **
e630: 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
e640: 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
e650: 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68  ns 1 and 2 of th
e660: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
e670: 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20  ect..  ** Those 
e680: 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65  below are for ve
e690: 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61  rsion 3 and grea
e6a0: 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ter..  */.  int 
e6b0: 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  (*xSetSystemCall
e6c0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
e6d0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
e6e0: 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  e, sqlite3_sysca
e6f0: 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74  ll_ptr);.  sqlit
e700: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28  e3_syscall_ptr (
e710: 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xGetSystemCall)
e720: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e730: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e740: 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  );.  const char 
e750: 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61  *(*xNextSystemCa
e760: 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
e770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
e780: 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  ame);.  /*.  ** 
e790: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e7a0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e7b0: 73 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66  s 1 through 3 of
e7c0: 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20   the sqlite_vfs 
e7d0: 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77  object..  ** New
e7e0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
e7f0: 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72  ppended in figur
e800: 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65  e versions.  The
e810: 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76   iVersion.  ** v
e820: 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d  alue will increm
e830: 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69  ent whenever thi
e840: 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f  s happens. .  */
e850: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e860: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
e870: 68 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d  he xAccess VFS m
e880: 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ethod.**.** Thes
e890: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
e8a0: 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nts can be used 
e8b0: 61 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72  as the third par
e8c0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
e8d0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20   xAccess method 
e8e0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  of an [sqlite3_v
e8f0: 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  fs] object.  The
e900: 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77  y determine.** w
e910: 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d  hat kind of perm
e920: 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63  issions the xAcc
e930: 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f  ess method is lo
e940: 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69  oking for..** Wi
e950: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
e960: 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63  _EXISTS, the xAc
e970: 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73  cess method.** s
e980: 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65  imply checks whe
e990: 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78  ther the file ex
e9a0: 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51  ists..** With SQ
e9b0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e9c0: 57 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65  WRITE, the xAcce
e9d0: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
e9e0: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
e9f0: 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20  named directory 
ea00: 69 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65  is both readable
ea10: 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a   and writable.**
ea20: 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73   (in other words
ea30: 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62  , if files can b
ea40: 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64  e added, removed
ea50: 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69  , and renamed wi
ea60: 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65  thin.** the dire
ea70: 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53  ctory)..** The S
ea80: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ea90: 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20  DWRITE constant 
eaa0: 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65  is currently use
eab0: 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a  d only by the.**
eac0: 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
ead0: 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
eae0: 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c  though this coul
eaf0: 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  d change in a fu
eb00: 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
eb10: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69  of SQLite..** Wi
eb20: 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  th SQLITE_ACCESS
eb30: 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65  _READ, the xAcce
eb40: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65  ss method.** che
eb50: 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20  cks whether the 
eb60: 66 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65  file is readable
eb70: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  .  The SQLITE_AC
eb80: 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61  CESS_READ consta
eb90: 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74  nt is.** current
eba0: 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67  ly unused, thoug
ebb0: 68 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73  h it might be us
ebc0: 65 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72  ed in a future r
ebd0: 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
ebe0: 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ite..*/.#define 
ebf0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
ec00: 49 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e  ISTS    0.#defin
ec10: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ec20: 52 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a  READWRITE 1   /*
ec30: 20 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20   Used by PRAGMA 
ec40: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
ec50: 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tory */.#define 
ec60: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
ec70: 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55  AD      2   /* U
ec80: 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  nused */../*.** 
ec90: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
eca0: 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b  for the xShmLock
ecb0: 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
ecc0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
ecd0: 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
ece0: 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63   the various loc
ecf0: 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a  king operations.
ed00: 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68  ** allowed by th
ed10: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
ed20: 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f  d of [sqlite3_io
ed30: 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a  _methods].  The.
ed40: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65  ** following are
ed50: 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20   the only legal 
ed60: 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20  combinations of 
ed70: 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20  flags to the.** 
ed80: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a  xShmLock method:
ed90: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
eda0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
edb0: 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
edc0: 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e  M_SHARED.** <li>
edd0: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
ede0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
edf0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e  XCLUSIVE.** <li>
ee00: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c    SQLITE_SHM_UNL
ee10: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
ee20: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
ee30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ee40: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
ee50: 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75  EXCLUSIVE.** </u
ee60: 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e  l>.**.** When un
ee70: 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d  locking, the sam
ee80: 65 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c  e SHARED or EXCL
ee90: 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20  USIVE flag must 
eea0: 62 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a  be supplied as.*
eeb0: 2a 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74  * was given on t
eec0: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
eed0: 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54   lock.  .**.** T
eee0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
eef0: 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f  od can transitio
ef00: 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  n between unlock
ef10: 65 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72  ed and SHARED or
ef20: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  .** between unlo
ef30: 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49  cked and EXCLUSI
ef40: 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74  VE.  It cannot t
ef50: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
ef60: 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20  n SHARED.** and 
ef70: 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64  EXCLUSIVE..*/.#d
ef80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ef90: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a  _UNLOCK       1.
efa0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
efb0: 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  HM_LOCK         
efc0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
efd0: 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20  _SHM_SHARED     
efe0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
eff0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
f000: 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      8../*.** CAP
f010: 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78  I3REF: Maximum x
f020: 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a  ShmLock index.**
f030: 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b  .** The xShmLock
f040: 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69   method on [sqli
f050: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
f060: 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a  may use values.*
f070: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
f080: 74 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64  this upper bound
f090: 20 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22   as its "offset"
f0a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68   argument..** Th
f0b0: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69  e SQLite core wi
f0c0: 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74  ll never attempt
f0d0: 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72   to acquire or r
f0e0: 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b  elease a.** lock
f0f0: 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73   outside of this
f100: 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e   range.*/.#defin
f110: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f  e SQLITE_SHM_NLO
f120: 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a  CK        8.../*
f130: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
f140: 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c  itialize The SQL
f150: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
f160: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f170: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f180: 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20  ine initializes 
f190: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69  the.** SQLite li
f1a0: 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c  brary.  ^The sql
f1b0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
f1c0: 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c  routine.** deall
f1d0: 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75  ocates any resou
f1e0: 72 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61  rces that were a
f1f0: 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69  llocated by sqli
f200: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f210: 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
f220: 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64  nes are designed
f230: 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65   to aid in proce
f240: 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
f250: 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77  n and.** shutdow
f260: 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79  n on embedded sy
f270: 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74  stems.  Workstat
f280: 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ion applications
f290: 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65   using.** SQLite
f2a0: 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74   normally do not
f2b0: 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20   need to invoke 
f2c0: 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20  either of these 
f2d0: 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
f2e0: 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
f2f0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f300: 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22  s an "effective"
f310: 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a   call if it is.*
f320: 2a 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  * the first time
f330: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f340: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
f350: 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65   during the life
f360: 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70  time of.** the p
f370: 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74  rocess, or if it
f380: 20 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69   is the first ti
f390: 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
f3a0: 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
f3b0: 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
f3c0: 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  a call to sqlite
f3d0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e  3_shutdown().  ^
f3e0: 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69  (Only an effecti
f3f0: 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71  ve call.** of sq
f400: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f410: 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74  () does any init
f420: 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c  ialization.  All
f430: 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20   other calls.** 
f440: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
f450: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63  ops.)^.**.** A c
f460: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f470: 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20  hutdown() is an 
f480: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
f490: 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
f4a0: 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73  rst.** call to s
f4b0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f4c0: 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74  ) since the last
f4d0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f4e0: 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a  ize().  ^(Only.*
f4f0: 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  * an effective c
f500: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f510: 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61  hutdown() does a
f520: 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74  ny deinitializat
f530: 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65  ion..** All othe
f540: 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f  r valid calls to
f550: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f560: 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73  n() are harmless
f570: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
f580: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69   The sqlite3_ini
f590: 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66  tialize() interf
f5a0: 61 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66  ace is threadsaf
f5b0: 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73  e, but sqlite3_s
f5c0: 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20  hutdown().** is 
f5d0: 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65  not.  The sqlite
f5e0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74  3_shutdown() int
f5f0: 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79  erface must only
f600: 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
f610: 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65  a.** single thre
f620: 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64  ad.  All open [d
f630: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f640: 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f  ons] must be clo
f650: 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f  sed and all.** o
f660: 74 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f  ther SQLite reso
f670: 75 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65  urces must be de
f680: 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20  allocated prior 
f690: 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  to invoking.** s
f6a0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f6b0: 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f  )..**.** Among o
f6c0: 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71  ther things, ^sq
f6d0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f6e0: 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a  () will invoke.*
f6f0: 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
f700: 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c  t().  Similarly,
f710: 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   ^sqlite3_shutdo
f720: 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76  wn().** will inv
f730: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  oke sqlite3_os_e
f740: 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nd()..**.** ^The
f750: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f760: 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ize() routine re
f770: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f780: 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a  ] on success..**
f790: 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65   ^If for some re
f7a0: 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ason, sqlite3_in
f7b0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e  itialize() is un
f7c0: 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69  able to initiali
f7d0: 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72  ze.** the librar
f7e0: 79 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73  y (perhaps it is
f7f0: 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
f800: 61 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73  ate a needed res
f810: 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73  ource such.** as
f820: 20 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74   a mutex) it ret
f830: 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63  urns an [error c
f840: 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20  ode] other than 
f850: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a  [SQLITE_OK]..**.
f860: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
f870: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75  initialize() rou
f880: 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69  tine is called i
f890: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e  nternally by man
f8a0: 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74  y other.** SQLit
f8b0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20  e interfaces so 
f8c0: 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74  that an applicat
f8d0: 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73  ion usually does
f8e0: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20   not need to.** 
f8f0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
f900: 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
f910: 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70  ctly.  For examp
f920: 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  le, [sqlite3_ope
f930: 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71  n()].** calls sq
f940: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f950: 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65  () so the SQLite
f960: 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65   library will be
f970: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a   automatically.*
f980: 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68  * initialized wh
f990: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  en [sqlite3_open
f9a0: 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66  ()] is called if
f9b0: 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69   it has not be i
f9c0: 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c  nitialized.** al
f9d0: 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72  ready.  ^However
f9e0: 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  , if SQLite is c
f9f0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
fa00: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
fa10: 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69  TOINIT].** compi
fa20: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
fa30: 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74  then the automat
fa40: 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ic calls to sqli
fa50: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fa60: 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20  .** are omitted 
fa70: 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  and the applicat
fa80: 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71  ion must call sq
fa90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
faa0: 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70  () directly.** p
fab0: 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e  rior to using an
fac0: 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  y other SQLite i
fad0: 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d  nterface.  For m
fae0: 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69  aximum portabili
faf0: 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63  ty,.** it is rec
fb00: 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
fb10: 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79  plications alway
fb20: 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  s invoke sqlite3
fb30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
fb40: 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20   directly prior 
fb50: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
fb60: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
fb70: 61 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c  ace.  Future rel
fb80: 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69  eases.** of SQLi
fb90: 74 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74  te may require t
fba0: 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  his.  In other w
fbb0: 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69  ords, the behavi
fbc0: 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20  or exhibited.** 
fbd0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
fbe0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
fbf0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
fc00: 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65  IT] might become
fc10: 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20   the.** default 
fc20: 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65  behavior in some
fc30: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
fc40: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
fc50: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
fc60: 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64  init() routine d
fc70: 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  oes operating-sy
fc80: 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a  stem specific.**
fc90: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
fca0: 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  of the SQLite li
fcb0: 62 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69  brary.  The sqli
fcc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fcd0: 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74  routine undoes t
fce0: 68 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c  he effect of sql
fcf0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
fd00: 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a   Typical tasks.*
fd10: 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74  * performed by t
fd20: 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e  hese routines in
fd30: 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e  clude allocation
fd40: 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e   or deallocation
fd50: 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65  .** of static re
fd60: 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c  sources, initial
fd70: 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61  ization of globa
fd80: 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20  l variables,.** 
fd90: 73 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66  setting up a def
fda0: 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
fdb0: 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65  s] module, or se
fdc0: 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65  tting up.** a de
fdd0: 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
fde0: 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ion using [sqlit
fdf0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
fe00: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
fe10: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
fe20: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73   invoke either s
fe30: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fe40: 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  .** or sqlite3_o
fe50: 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79  s_end() directly
fe60: 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
fe70: 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69  on should only i
fe80: 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33  nvoke.** sqlite3
fe90: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
fea0: 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  d sqlite3_shutdo
feb0: 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74  wn().  The sqlit
fec0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
fed0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c  interface is cal
fee0: 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  led automaticall
fef0: 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  y by sqlite3_ini
ff00: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a  tialize() and.**
ff10: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
ff20: 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73  ) is called by s
ff30: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ff40: 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a  ).  Appropriate.
ff50: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ff60: 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  ns for sqlite3_o
ff70: 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c  s_init() and sql
ff80: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
ff90: 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20   are built into 
ffa0: 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69  SQLite when it i
ffb0: 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55  s compiled for U
ffc0: 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72  nix, Windows, or
ffd0: 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b   OS/2..** When [
ffe0: 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20  custom builds | 
fff0: 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20  built for other 
10000 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75  platforms].** (u
10010 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
10020 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d  _OS_OTHER=1] com
10030 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
10040 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61  ion) the applica
10050 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79  tion must supply
10060 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c   a suitable impl
10070 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  ementation for.*
10080 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  * sqlite3_os_ini
10090 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
100a0 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70  os_end().  An ap
100b0 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69  plication-suppli
100c0 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ed.** implementa
100d0 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  tion of sqlite3_
100e0 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c  os_init() or sql
100f0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a  ite3_os_end().**
10100 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51   must return [SQ
10110 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
10120 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68  ess and some oth
10130 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  er [error code] 
10140 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e  upon.** failure.
10150 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
10160 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29  initialize(void)
10170 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68  ;.int sqlite3_sh
10180 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e  utdown(void);.in
10190 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
101a0 74 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  t(void);.int sql
101b0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
101c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
101d0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
101e0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
101f0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
10200 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
10210 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
10220 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
10230 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10240 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
10250 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
10260 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
10270 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
10280 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
10290 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
102a0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
102b0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
102c0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
102d0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
102e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
102f0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
10300 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
10310 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
10320 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
10330 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
10340 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
10350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
10360 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
10370 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
10380 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
10390 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
103a0 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
103b0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
103c0 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
103d0 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
103e0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
103f0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
10400 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
10410 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
10420 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
10430 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
10440 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
10450 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
10460 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
10470 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
10480 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
10490 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
104a0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
104b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
104c0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
104d0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
104e0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
104f0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
10500 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
10510 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
10520 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
10530 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
10540 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
10550 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
10560 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
10570 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
10580 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
10590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
105a0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
105b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
105c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
105d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
105e0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
105f0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
10600 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
10610 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
10620 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
10630 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
10640 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
10650 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
10660 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
10670 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
10680 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
10690 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
106a0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
106b0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
106c0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
106d0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
106e0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
106f0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
10700 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
10710 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
10720 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
10730 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
10740 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
10750 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
10760 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
10770 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
10780 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
10790 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
107a0 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
107b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
107c0 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
107d0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
107e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
107f0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10800 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
10810 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
10820 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
10830 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10840 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
10850 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
10860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10870 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
10880 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
10890 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
108a0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
108b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
108c0 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
108d0 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
108e0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
108f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
10900 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
10910 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
10920 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
10930 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
10940 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
10950 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
10960 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
10970 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
10980 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
10990 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
109a0 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
109b0 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
109c0 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
109d0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
109e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
109f0 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
10a00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
10a10 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
10a20 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
10a30 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
10a40 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
10a50 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
10a60 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  */.int sqlite3_d
10a70 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
10a80 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
10a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10aa0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
10ab0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
10ac0 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
10ad0 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
10ae0 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
10af0 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
10b00 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
10b10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
10b20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
10b30 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
10b40 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
10b50 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
10b60 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
10b70 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
10b80 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
10b90 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
10ba0 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
10bb0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
10bc0 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
10bd0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
10be0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
10bf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
10c00 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
10c10 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
10c20 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
10c30 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
10c40 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
10c50 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
10c60 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
10c70 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
10c80 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
10c90 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
10ca0 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
10cb0 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
10cc0 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10cd0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10ce0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
10cf0 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
10d00 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
10d10 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
10d20 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
10d30 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
10d40 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
10d50 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
10d60 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
10d70 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
10d80 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
10d90 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
10da0 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
10db0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
10dc0 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
10dd0 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
10de0 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
10df0 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
10e00 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
10e10 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
10e20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
10e30 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
10e40 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
10e50 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
10e60 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
10e70 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
10e80 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
10e90 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
10ea0 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
10eb0 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
10ec0 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
10ed0 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
10ee0 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
10ef0 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
10f00 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
10f10 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
10f20 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
10f30 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
10f40 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
10f50 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
10f60 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
10f70 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
10f80 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
10f90 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
10fa0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
10fb0 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
10fc0 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
10fd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
10fe0 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
10ff0 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
11000 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
11010 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
11020 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
11030 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
11040 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
11050 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
11060 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
11070 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
11080 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
11090 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
110a0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
110b0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
110c0 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
110d0 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
110e0 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
110f0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
11100 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
11110 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
11120 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
11130 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
11140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11150 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
11160 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
11170 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
11180 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
11190 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
111a0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
111b0 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
111c0 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
111d0 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
111e0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
111f0 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
11200 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
11210 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
11220 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11230 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
11240 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
11250 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
11260 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
11270 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
11280 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
11290 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
112a0 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
112b0 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
112c0 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
112d0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
112e0 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
112f0 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
11300 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
11310 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
11320 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
11330 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
11340 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
11350 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
11360 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
11370 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
11380 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
11390 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
113a0 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
113b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
113c0 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
113d0 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
113e0 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
113f0 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
11400 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
11410 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
11420 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
11430 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
11440 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
11450 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
11460 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
11470 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
11480 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
11490 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
114a0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
114b0 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
114c0 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
114d0 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
114e0 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
114f0 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
11500 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
11510 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
11520 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
11530 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
11540 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
11550 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
11560 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
11570 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
11580 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
11590 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
115a0 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
115b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
115c0 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
115d0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
115e0 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
115f0 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
11600 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
11610 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
11620 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
11630 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
11640 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
11650 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
11660 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
11670 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
11680 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
11690 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
116a0 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
116b0 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
116c0 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
116d0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
116e0 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
116f0 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
11700 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
11710 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
11720 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
11730 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
11740 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
11750 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
11760 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
11770 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
11780 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
11790 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
117a0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
117b0 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
117c0 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
117d0 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
117e0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
117f0 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
11800 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11810 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
11820 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
11830 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
11840 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
11850 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
11860 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
11870 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
11880 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
11890 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
118a0 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
118b0 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
118c0 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
118d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
118e0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
118f0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
11900 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
11910 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
11920 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
11930 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
11940 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
11950 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
11960 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
11970 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
11980 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
11990 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
119a0 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
119b0 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
119c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
119d0 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
119e0 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
119f0 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
11a00 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
11a10 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
11a20 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
11a30 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
11a40 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11a50 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
11a60 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
11a70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
11a80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
11a90 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
11aa0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
11ab0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11ac0 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
11ad0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
11ae0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
11af0 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
11b00 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11b10 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
11b20 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
11b30 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
11b40 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
11b50 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
11b60 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
11b70 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
11b80 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
11b90 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
11ba0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
11bb0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
11bc0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
11bd0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
11be0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
11bf0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
11c00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11c10 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
11c20 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
11c30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
11c40 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
11c50 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11c60 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
11c70 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
11c80 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
11c90 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
11ca0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
11cb0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
11cc0 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
11cd0 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
11ce0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
11cf0 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
11d00 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
11d10 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
11d20 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
11d30 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
11d40 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
11d50 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
11d60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d70 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d90 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11da0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11db0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11dc0 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
11dd0 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
11de0 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
11df0 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
11e00 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
11e10 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
11e20 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
11e30 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
11e40 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
11e50 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11e60 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
11e70 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
11e80 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
11e90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
11ea0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11eb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11ec0 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
11ed0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11ee0 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
11ef0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11f00 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11f10 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11f20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11f30 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11f40 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
11f50 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
11f60 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
11f70 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
11f80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11f90 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
11fa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11fb0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
11fc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
11fd0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
11fe0 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
11ff0 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
12000 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
12010 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
12020 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
12030 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
12040 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
12050 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
12060 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
12070 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
12080 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
12090 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
120a0 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
120b0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
120c0 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
120d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
120e0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
120f0 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
12100 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
12110 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
12120 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
12130 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
12140 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12150 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12160 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
12170 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
12180 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
12190 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
121a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
121b0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
121c0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
121d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
121e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
121f0 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
12200 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12210 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
12230 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
12240 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
12250 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
12260 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
12270 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
12280 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
12290 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
122a0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
122b0 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
122c0 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
122d0 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
122e0 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
122f0 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
12300 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
12310 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
12320 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12330 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
12340 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
12350 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
12360 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
12370 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
12380 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12390 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
123a0 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
123b0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
123c0 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
123d0 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
123e0 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
123f0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
12400 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
12410 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
12420 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
12430 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
12440 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
12450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
12460 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
12470 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
12480 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
12490 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
124a0 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
124b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
124c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
124d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
124e0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
124f0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
12500 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
12510 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
12520 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
12530 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
12540 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
12550 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
12560 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
12570 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12580 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
12590 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
125a0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
125b0 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
125c0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
125d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
125e0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
125f0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12600 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
12610 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
12620 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
12630 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
12640 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
12650 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
12660 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
12670 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
12680 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12690 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
126a0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
126b0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
126c0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
126d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
126e0 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
126f0 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
12700 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
12710 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12720 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12730 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
12740 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
12750 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
12760 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
12770 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
12780 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
12790 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
127a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
127b0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
127c0 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
127d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
127e0 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
127f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12800 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
12810 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
12820 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
12830 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
12840 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
12850 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
12860 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
12870 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
12880 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
12890 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
128a0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
128b0 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
128c0 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
128d0 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
128e0 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
128f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
12900 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
12910 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
12920 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
12930 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
12940 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
12950 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12960 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
12970 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
12980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
12990 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
129a0 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
129b0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
129c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
129e0 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
129f0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
12a00 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
12a10 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
12a20 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69  G_MEMSTATUS opti
12a30 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
12a40 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
12a50 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72   int,.** interpr
12a60 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
12a70 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
12a80 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
12a90 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a   collection of.*
12aa0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12ab0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
12ac0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
12ad0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12ae0 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  ics are.** disab
12af0 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
12b00 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
12b10 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
12b20 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
12b30 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
12b40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
12b50 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
12b60 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
12b70 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
12b80 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12b90 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
12ba0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
12bb0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
12bc0 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  s64()].**   </ul
12bd0 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
12be0 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
12bf0 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
12c00 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
12c10 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
12c20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
12c30 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
12c40 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
12c50 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
12c60 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
12c70 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
12c80 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12c90 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
12ca0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12cb0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
12cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
12cd0 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
12ce0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
12cf0 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
12d00 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
12d10 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
12d20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
12d30 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
12d40 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
12d50 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
12d60 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
12d70 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
12d80 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
12d90 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
12da0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
12db0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
12dc0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
12dd0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
12de0 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
12df0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
12e00 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
12e10 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
12e20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
12e30 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
12e40 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
12e50 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
12e60 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
12e70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
12e80 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
12e90 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
12ea0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
12eb0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
12ec0 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
12ed0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
12ee0 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12ef0 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
12f00 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
12f10 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
12f20 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
12f30 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
12f40 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
12f50 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
12f60 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
12f70 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
12f80 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
12f90 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
12fa0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
12fb0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
12fc0 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
12fd0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
12fe0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
12ff0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
13000 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
13010 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
13020 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
13030 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
13040 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
13050 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
13060 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
13070 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
13080 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
13090 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
130a0 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
130b0 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
130c0 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
130d0 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
130e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
130f0 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
13100 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
13110 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
13120 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
13130 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
13140 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13150 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
13160 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
13170 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
13180 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
131a0 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
131b0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
131c0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
131d0 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
131e0 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
131f0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
13200 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
13210 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
13220 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
13230 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
13240 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
13250 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
13260 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
13270 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
13280 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13290 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
132a0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
132b0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
132c0 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
132d0 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
132e0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
132f0 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
13300 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
13310 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
13320 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
13330 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
13340 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
13350 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
13360 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13370 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
13380 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
13390 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
133a0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
133b0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
133c0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
133d0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
133e0 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
133f0 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
13400 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
13410 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
13420 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
13430 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
13440 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
13450 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
13460 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
13470 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13480 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
13490 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
134a0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
134b0 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
134c0 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
134d0 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
134e0 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
134f0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
13500 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
13510 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
13520 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
13530 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
13540 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
13550 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
13560 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
13570 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
13580 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
13590 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
135a0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
135b0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
135c0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
135d0 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
135e0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
135f0 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
13600 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
13610 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
13620 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
13630 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
13640 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
13650 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
13660 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
13670 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
13680 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
13690 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
136a0 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
136b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
136c0 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
136d0 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
136e0 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
136f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13700 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
13710 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
13720 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
13730 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
13740 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
13750 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13760 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
13770 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
13780 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13790 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
137a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
137b0 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
137c0 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
137d0 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
137e0 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
137f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
13800 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
13810 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
13820 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
13830 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
13840 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
13850 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
13860 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
13870 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
13880 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
13890 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
138a0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
138b0 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
138c0 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
138d0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
138e0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
138f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
13900 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
13910 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
13920 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13930 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13940 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13950 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13960 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13970 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13980 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13990 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
139a0 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
139b0 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
139c0 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
139d0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
139e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
139f0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
13a00 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
13a10 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
13a20 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13a30 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13a40 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13a50 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13a60 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13a70 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
13a80 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
13a90 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
13aa0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
13ab0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
13ac0 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
13ad0 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
13ae0 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
13af0 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
13b00 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
13b10 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13b20 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
13b30 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
13b40 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
13b50 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
13b60 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
13b70 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
13b80 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
13b90 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
13ba0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
13bb0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
13bc0 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
13bd0 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
13be0 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
13bf0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
13c00 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
13c10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
13c20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
13c30 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
13c40 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
13c50 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13c60 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13c70 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
13c80 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
13c90 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13ca0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13cb0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
13cc0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
13cd0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
13ce0 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
13cf0 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
13d00 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
13d10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
13d20 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
13d30 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13d40 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
13d50 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
13d60 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
13d70 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
13d80 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
13d90 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
13da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
13db0 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
13dc0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
13dd0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
13de0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
13df0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
13e00 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
13e10 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
13e20 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
13e30 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
13e40 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
13e50 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
13e60 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
13e70 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13e80 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
13e90 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
13ea0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13eb0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
13ec0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
13ed0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
13ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13ef0 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
13f00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13f10 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
13f20 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
13f30 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
13f40 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
13f50 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
13f60 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
13f70 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
13f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
13f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
13fa0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
13fb0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
13fc0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
13fd0 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
13fe0 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
13ff0 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
14000 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
14010 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
14020 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
14030 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
14040 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
14050 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
14060 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
14070 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
14080 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
14090 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
140a0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
140b0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
140c0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
140d0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
140e0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
140f0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14100 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14110 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14120 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
14130 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
14140 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
14150 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
14160 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
14170 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
14180 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
14190 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
141a0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
141b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
141c0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
141d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
141e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
141f0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14200 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
14210 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
14220 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14230 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14240 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
14250 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14260 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
14270 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
14280 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
14290 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
142a0 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
142b0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
142c0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
142d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
142e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
142f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
14300 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
14310 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
14320 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
14330 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
14340 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
14350 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
14360 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
14370 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
14380 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
14390 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
143a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
143b0 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
143c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
143d0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
143e0 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
143f0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
14400 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14410 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
14420 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
14430 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14440 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
14450 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14460 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
14470 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
14480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14490 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
144a0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
144b0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
144c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
144d0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
144e0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
144f0 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
14500 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
14510 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
14520 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
14530 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
14540 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
14550 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
14560 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
14570 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
14580 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
14590 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
145a0 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
145b0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
145c0 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
145d0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
145e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
145f0 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
14600 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14610 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
14620 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
14630 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
14640 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
14650 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
14660 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
14670 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
14680 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
14690 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
146a0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
146b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
146c0 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
146d0 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
146e0 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
146f0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
14700 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
14710 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
14720 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
14730 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
14740 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14750 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
14760 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
14770 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
14780 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
14790 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
147a0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
147b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
147c0 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
147d0 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
147e0 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
147f0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
14800 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
14810 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
14820 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
14830 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
14840 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
14850 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
14860 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
14870 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
14880 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
14890 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
148a0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
148b0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
148c0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
148d0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
148e0 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
148f0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
14900 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
14910 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
14920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14930 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
14940 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
14950 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
14960 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
14970 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
14980 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
14990 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
149a0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
149b0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
149c0 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
149d0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
149e0 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
149f0 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
14a00 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
14a10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
14a20 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
14a30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
14a40 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
14a50 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
14a60 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
14a70 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
14a80 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
14a90 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
14aa0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
14ab0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
14ac0 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
14ad0 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
14ae0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
14af0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
14b00 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
14b10 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
14b20 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14b30 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
14b40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
14b50 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
14b60 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
14b70 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
14b80 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14b90 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
14ba0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14bb0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
14bc0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14bd0 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
14be0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
14bf0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
14c00 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
14c10 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
14c20 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
14c30 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14c40 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14c50 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
14c60 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
14c70 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
14c80 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
14c90 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
14ca0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
14cb0 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
14cc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
14cd0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
14ce0 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
14cf0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
14d00 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
14d10 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
14d20 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
14d30 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
14d40 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
14d50 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
14d60 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
14d70 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
14d80 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
14d90 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
14da0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
14db0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
14dc0 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
14dd0 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
14de0 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
14df0 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
14e00 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
14e10 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
14e20 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
14e30 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
14e40 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
14e50 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
14e60 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
14e70 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
14e80 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
14e90 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
14ea0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
14eb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
14ec0 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
14ed0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
14ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14ef0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
14f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14f10 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14f20 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
14f30 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14f40 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
14f50 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
14f60 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14f70 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
14f80 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
14f90 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
14fa0 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14fb0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
14fc0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
14fd0 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
14fe0 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
14ff0 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
15000 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
15010 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15020 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
15030 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
15040 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
15050 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
15060 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15070 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
15080 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
15090 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
150a0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
150b0 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
150c0 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
150d0 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
150e0 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
150f0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
15100 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
15110 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
15120 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
15130 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
15140 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
15150 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
15160 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
15170 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
15180 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
15190 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
151a0 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
151b0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
151c0 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
151d0 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
151e0 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
151f0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
15200 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
15210 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
15220 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15230 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
15240 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15250 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
15260 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
15270 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
15280 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
15290 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
152a0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
152b0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
152c0 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
152d0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
152e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
152f0 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
15300 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
15310 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15320 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
15330 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
15340 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
15350 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
15360 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
15370 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15380 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
15390 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
153a0 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
153b0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
153c0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
153d0 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
153e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
153f0 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
15400 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
15410 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
15420 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
15430 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
15440 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
15450 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
15460 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
15470 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
15480 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
15490 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
154a0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
154b0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
154c0 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
154d0 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
154e0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
154f0 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
15500 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15510 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
15520 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
15530 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
15540 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
15550 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
15560 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
15570 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
15580 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
15590 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
155a0 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
155b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
155c0 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
155d0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
155e0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
155f0 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
15600 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
15610 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
15620 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
15630 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
15640 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
15650 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
15660 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
15670 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
15680 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
15690 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
156a0 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
156b0 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
156c0 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
156d0 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
156e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
156f0 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
15700 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
15710 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
15720 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
15730 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
15740 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
15750 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15760 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
15770 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15780 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
15790 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
157a0 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
157b0 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
157c0 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
157d0 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
157e0 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
157f0 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
15800 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
15810 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
15820 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
15830 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
15840 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
15850 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
15860 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
15870 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
15880 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
15890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
158a0 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
158b0 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
158c0 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
158d0 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
158e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
158f0 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
15900 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
15910 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
15920 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
15930 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
15940 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
15950 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
15960 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
15970 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
15980 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
15990 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
159a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
159b0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
159c0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
159d0 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
159e0 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
159f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
15a00 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
15a10 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
15a20 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
15a30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
15a40 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
15a50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
15a60 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
15a70 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15a80 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15a90 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
15aa0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15ab0 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
15ac0 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
15ad0 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
15ae0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
15af0 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
15b00 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
15b10 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
15b20 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
15b30 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
15b40 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15b50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
15b60 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
15b70 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
15b80 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
15b90 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
15ba0 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
15bb0 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
15bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
15bd0 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
15be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
15bf0 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
15c00 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15c10 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15c20 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
15c30 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
15c40 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
15c50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
15c60 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
15c70 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
15c80 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
15c90 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
15ca0 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
15cb0 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
15cc0 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
15cd0 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
15ce0 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
15cf0 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
15d00 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
15d10 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
15d20 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
15d30 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
15d40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
15d50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15d60 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
15d70 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15d80 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
15d90 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
15da0 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
15db0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15dc0 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
15dd0 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
15de0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
15df0 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
15e00 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
15e10 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
15e20 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
15e30 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
15e40 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
15e50 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
15e60 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
15e70 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
15e80 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15e90 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
15ea0 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
15eb0 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
15ec0 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
15ed0 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
15ee0 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
15ef0 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
15f00 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
15f10 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
15f20 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
15f30 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
15f40 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
15f50 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
15f60 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
15f70 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
15f80 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
15f90 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
15fa0 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  lue..** </dl>.*/
15fb0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15fc0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
15fd0 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
15fe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15ff0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
16000 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
16010 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
16020 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
16030 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
16040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16050 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16060 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
16070 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
16080 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
16090 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
160a0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
160b0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
160c0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
160d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
160e0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
160f0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
16100 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
16110 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16120 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
16130 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
16140 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
16150 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16160 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
16170 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
16180 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
16190 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
161a0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
161b0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
161c0 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
161d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
161e0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
161f0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16200 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
16210 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
16220 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
16230 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
16240 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
16250 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
16260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
16270 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
16280 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
16290 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
162a0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
162b0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
162c0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
162d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
162e0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
162f0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
16300 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
16310 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
16320 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
16330 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16340 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
16350 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
16360 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
16370 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
16380 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
16390 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
163a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
163b0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
163c0 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
163d0 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
163e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
163f0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
16400 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
16410 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
16420 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
16430 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
16440 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
16450 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
16460 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16470 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
16480 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
16490 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
164a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
164b0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
164c0 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
164d0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
164e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
164f0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
16500 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
16510 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
16520 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16530 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
16540 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
16550 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
16560 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16570 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
16580 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
16590 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
165a0 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a */../*.** CAPI
165b0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
165c0 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
165d0 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
165e0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
165f0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
16600 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
16610 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16620 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
16630 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
16640 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
16650 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
16660 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
16670 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
16680 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
16690 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
166a0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
166b0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
166c0 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
166d0 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
166e0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
166f0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
16700 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
16710 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
16720 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
16730 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
16740 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
16750 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
16760 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
16770 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
16780 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
16790 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
167a0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
167b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
167c0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
167d0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
167e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
167f0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
16800 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
16810 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
16820 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
16830 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16840 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
16850 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
16860 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
16870 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
16880 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
16890 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
168a0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
168b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
168c0 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
168d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
168e0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
168f0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
16900 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
16910 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
16920 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
16930 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
16940 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
16950 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
16960 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
16970 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
16980 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
16990 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
169a0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
169b0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
169c0 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
169d0 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
169e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
169f0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
16a00 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
16a10 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
16a20 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
16a30 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
16a40 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
16a50 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
16a60 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
16a70 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
16a80 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
16a90 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16aa0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
16ab0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
16ac0 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
16ad0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
16ae0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
16af0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
16b00 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16b10 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
16b20 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
16b30 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
16b40 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
16b50 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
16b60 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
16b70 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
16b80 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
16b90 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
16ba0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
16bb0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
16bc0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
16bd0 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
16be0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
16bf0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
16c00 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
16c10 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
16c20 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
16c30 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
16c40 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
16c50 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
16c60 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
16c70 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
16c80 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
16c90 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
16ca0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
16cb0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
16cc0 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
16cd0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
16ce0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
16cf0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
16d00 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
16d10 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
16d20 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
16d30 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
16d40 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
16d50 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
16d60 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
16d70 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
16d80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
16d90 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
16da0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16db0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16dc0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
16dd0 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
16de0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
16df0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
16e00 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
16e10 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
16e20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
16e30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16e40 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
16e50 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
16e60 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
16e70 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
16e80 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
16e90 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
16ea0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
16eb0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
16ec0 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
16ed0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
16ee0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
16ef0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
16f00 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
16f10 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
16f20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
16f30 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
16f40 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
16f50 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
16f60 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
16f70 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
16f80 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
16f90 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
16fa0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
16fb0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
16fc0 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
16fd0 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
16fe0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
16ff0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
17000 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
17010 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
17020 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
17030 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
17040 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17050 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
17060 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
17070 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
17080 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
17090 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
170a0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
170b0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
170c0 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
170d0 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
170e0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
170f0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
17100 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
17110 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
17120 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
17130 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
17140 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
17150 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
17160 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
17170 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
17180 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
17190 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
171a0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
171b0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
171c0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
171d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
171e0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
171f0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
17200 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
17210 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
17220 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
17230 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
17240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17250 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
17260 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
17270 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17280 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
17290 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
172a0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
172b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
172c0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
172d0 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
172e0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
172f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
17300 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
17310 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
17320 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
17330 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
17340 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
17350 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
17360 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
17370 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
17380 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
17390 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
173a0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
173b0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
173c0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
173d0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
173e0 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
173f0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
17400 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
17410 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
17420 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
17430 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
17440 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17450 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
17460 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
17470 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
17480 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
17490 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
174a0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
174b0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
174c0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
174d0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
174e0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
174f0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
17500 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
17510 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
17520 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
17530 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
17540 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
17550 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
17560 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
17570 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
17580 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
17590 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
175a0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
175b0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
175c0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
175d0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
175e0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
175f0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
17600 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
17610 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
17620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17630 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
17640 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
17650 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
17660 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
17670 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
17680 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
17690 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
176a0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
176b0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
176c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
176d0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
176e0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
176f0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
17700 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
17710 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
17720 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
17730 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
17740 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
17750 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
17760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
17770 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
17780 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17790 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
177a0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
177b0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
177c0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
177d0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
177e0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
177f0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
17800 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
17810 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
17820 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
17830 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
17840 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
17850 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
17860 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
17870 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
17880 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
17890 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
178a0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
178b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
178c0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
178d0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
178e0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
178f0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
17900 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
17910 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
17920 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
17930 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
17940 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
17950 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
17960 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
17970 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
17980 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
17990 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
179a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
179b0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
179c0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
179d0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
179e0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
179f0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
17a00 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
17a10 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
17a20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
17a30 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
17a40 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
17a50 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
17a60 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
17a70 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
17a80 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
17a90 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
17aa0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
17ab0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
17ac0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
17ad0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
17ae0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
17af0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
17b00 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
17b10 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
17b20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
17b30 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
17b40 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
17b50 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
17b60 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
17b70 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
17b80 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
17b90 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
17ba0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
17bb0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
17bc0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
17bd0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
17be0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
17bf0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
17c00 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
17c10 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
17c20 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
17c30 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
17c40 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
17c50 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
17c60 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
17c70 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
17c80 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
17c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
17ca0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
17cb0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
17cc0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
17cd0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
17ce0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
17cf0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
17d00 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
17d10 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17d20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
17d30 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
17d40 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
17d50 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
17d60 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
17d70 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
17d80 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
17d90 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
17da0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
17db0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
17dc0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
17dd0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
17de0 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
17df0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
17e00 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
17e10 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
17e20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
17e30 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
17e40 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
17e50 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
17e60 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
17e70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17e80 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
17e90 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
17ea0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
17eb0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
17ec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
17ed0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
17ee0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
17ef0 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
17f00 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
17f10 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
17f20 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
17f30 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17f40 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
17f50 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
17f60 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
17f70 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
17f80 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
17f90 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
17fa0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
17fb0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
17fc0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
17fd0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
17fe0 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
17ff0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
18000 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
18010 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
18020 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
18030 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
18040 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
18050 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
18060 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
18070 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
18080 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
18090 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
180a0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
180b0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
180c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
180d0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
180e0 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
180f0 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
18100 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
18110 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
18120 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
18130 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
18140 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
18150 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
18160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
18170 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
18180 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
18190 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
181a0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
181b0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
181c0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
181d0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
181e0 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
181f0 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
18200 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
18210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
18220 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
18230 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
18240 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
18250 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
18260 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
18270 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
18280 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
18290 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
182a0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
182b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
182c0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
182d0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
182e0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
182f0 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
18300 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
18310 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
18320 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
18330 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
18340 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
18350 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
18360 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
18370 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
18380 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
18390 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
183a0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
183b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
183c0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
183d0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
183e0 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
183f0 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
18400 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
18410 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
18420 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
18430 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
18440 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
18450 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
18460 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
18470 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
18480 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
18490 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
184a0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
184b0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
184c0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
184d0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
184e0 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
184f0 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
18500 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
18510 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
18520 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
18530 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
18540 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
18550 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
18560 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
18570 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
18580 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
18590 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
185a0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
185b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
185c0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
185d0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
185e0 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
185f0 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
18600 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
18610 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
18620 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
18630 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
18640 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
18650 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
18660 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
18670 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
18680 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
18690 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
186a0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
186b0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
186c0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
186d0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
186e0 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
186f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18700 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18710 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18720 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18730 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18740 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18750 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
18760 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
18770 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
18780 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
18790 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
187a0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
187b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
187c0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
187d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
187e0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
187f0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
18800 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
18810 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
18820 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
18830 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
18840 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
18850 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
18860 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
18870 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
18880 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
18890 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
188a0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
188b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
188c0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
188d0 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
188e0 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
188f0 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
18900 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
18910 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
18920 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
18930 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
18940 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
18950 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18960 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18970 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
18980 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
18990 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
189a0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
189b0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
189c0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
189d0 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
189e0 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
189f0 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
18a00 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
18a10 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
18a20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
18a30 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
18a40 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
18a50 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
18a60 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
18a70 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
18a80 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
18a90 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
18aa0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
18ab0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
18ac0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
18ad0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
18ae0 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
18af0 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
18b00 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
18b10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18b20 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
18b30 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
18b40 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
18b50 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
18b60 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
18b70 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
18b80 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
18b90 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
18ba0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
18bb0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18bc0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
18bd0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
18be0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
18bf0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
18c00 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
18c10 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
18c20 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
18c30 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
18c40 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
18c50 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
18c60 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
18c70 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
18c80 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
18c90 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
18ca0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
18cb0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
18cc0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
18cd0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
18ce0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
18cf0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
18d00 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
18d10 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18d20 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18d30 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18d40 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18d50 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18d60 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18d70 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
18d80 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
18d90 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
18da0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
18db0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
18dc0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
18dd0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18de0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
18df0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
18e00 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
18e10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18e20 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18e30 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18e40 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18e50 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18e60 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18e70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18e80 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
18e90 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
18ea0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
18eb0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
18ec0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
18ed0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
18ee0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
18ef0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
18f00 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
18f10 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18f20 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18f30 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18f40 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18f50 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18f60 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18f70 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18f80 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
18f90 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
18fa0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
18fb0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
18fc0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
18fd0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
18fe0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
18ff0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
19000 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
19010 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
19020 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
19030 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
19040 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
19050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19060 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
19070 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
19080 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
19090 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
190a0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
190b0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
190c0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
190d0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
190e0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
190f0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
19100 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
19110 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
19120 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
19130 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
19140 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
19150 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19160 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
19170 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
19180 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
19190 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
191a0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
191b0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
191c0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
191d0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
191e0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
191f0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
19200 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
19210 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
19220 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
19230 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
19240 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
19250 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
19260 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
19270 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
19280 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
19290 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
192a0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
192b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
192c0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
192d0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
192e0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
192f0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
19300 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
19310 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
19320 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
19330 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19340 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
19350 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
19360 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
19370 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
19380 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
19390 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
193a0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
193b0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
193c0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
193d0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
193e0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
193f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
19400 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
19410 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
19420 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
19430 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
19440 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
19450 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
19460 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19470 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
19480 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
19490 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
194a0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
194b0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
194c0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
194d0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
194e0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
194f0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
19500 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
19510 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
19520 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
19530 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
19540 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
19550 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
19560 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
19570 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
19580 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
19590 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
195a0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
195b0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
195c0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
195d0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
195e0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
195f0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
19600 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
19610 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
19620 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
19630 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
19640 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
19650 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
19660 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
19670 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
19680 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
19690 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
196a0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
196b0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
196c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
196d0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
196e0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
196f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
19700 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
19710 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
19720 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
19730 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
19740 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
19750 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
19760 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
19770 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
19780 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
19790 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
197a0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
197b0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
197c0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
197d0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
197e0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
197f0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
19800 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
19810 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
19820 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
19830 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
19840 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
19850 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
19860 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
19870 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
19880 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
19890 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
198a0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
198b0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
198c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
198d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
198e0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
198f0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
19900 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
19910 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
19920 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
19930 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
19940 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
19950 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
19960 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
19970 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
19980 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
19990 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
199a0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
199b0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
199c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
199d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
199e0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
199f0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
19a00 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
19a10 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
19a20 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
19a30 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
19a40 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
19a50 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
19a60 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
19a70 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
19a80 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
19a90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
19aa0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
19ab0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
19ac0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
19ad0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
19ae0 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
19af0 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
19b00 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
19b10 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
19b20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19b30 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
19b40 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19b50 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
19b60 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
19b70 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
19b80 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
19b90 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
19ba0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
19bb0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
19bc0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
19bd0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
19be0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
19bf0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
19c00 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
19c10 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
19c20 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
19c30 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
19c40 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
19c50 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
19c60 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
19c70 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
19c80 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
19c90 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
19ca0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
19cb0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19cc0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
19cd0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
19ce0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
19cf0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
19d00 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
19d10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
19d20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19d30 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
19d40 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
19d50 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
19d60 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
19d70 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
19d80 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
19d90 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
19da0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
19db0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
19dc0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
19dd0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
19de0 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
19df0 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
19e00 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
19e10 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
19e20 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
19e30 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
19e40 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
19e50 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
19e60 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
19e70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
19e80 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
19e90 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
19ea0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
19eb0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
19ec0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
19ed0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
19ee0 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
19ef0 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
19f00 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
19f10 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
19f20 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
19f30 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
19f40 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
19f50 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
19f60 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
19f70 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
19f80 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
19f90 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
19fa0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
19fb0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
19fc0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
19fd0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
19fe0 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
19ff0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1a000 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1a010 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1a020 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1a030 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1a040 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1a050 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1a060 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1a070 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1a080 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1a090 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1a0a0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1a0b0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1a0c0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1a0d0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1a0e0 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1a0f0 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1a100 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1a110 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1a120 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1a130 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1a140 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1a150 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1a160 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1a170 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1a180 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1a190 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1a1a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1a1b0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1a1c0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1a1d0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1a1e0 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1a1f0 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1a200 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1a210 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1a220 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1a230 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1a240 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1a250 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1a260 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1a270 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1a280 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1a290 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1a2a0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1a2b0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1a2c0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1a2d0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1a2e0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1a2f0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1a300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1a310 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1a320 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1a330 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1a340 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1a350 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1a360 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1a370 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1a380 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1a390 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1a3a0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1a3b0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1a3c0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1a3d0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1a3e0 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1a3f0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1a400 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1a410 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1a420 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1a430 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1a440 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a450 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1a460 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1a470 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1a480 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1a490 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1a4a0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1a4b0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1a4c0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1a4d0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1a4e0 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1a4f0 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1a500 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1a510 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1a520 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1a530 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1a540 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1a550 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1a560 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a570 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1a580 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1a590 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1a5a0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1a5b0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1a5c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a5d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1a5e0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1a5f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1a600 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1a610 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1a620 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1a630 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1a640 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1a650 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1a660 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1a670 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1a680 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1a690 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1a6a0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1a6b0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1a6c0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1a6d0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1a6e0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1a6f0 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1a700 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1a710 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1a720 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1a730 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1a740 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1a750 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1a760 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1a770 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1a780 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1a790 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1a7a0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1a7b0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1a7c0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1a7d0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1a7e0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1a7f0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1a800 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1a810 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1a820 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1a830 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1a840 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1a850 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1a860 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1a870 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1a880 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1a890 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1a8a0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1a8b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1a8c0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1a8d0 75 74 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ut].*/.int sqlit
1a8e0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1a8f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1a900 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a910 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1a920 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1a930 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1a940 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a950 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1a960 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1a970 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1a980 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1a990 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1a9a0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1a9b0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1a9c0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1a9d0 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1a9e0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1a9f0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1aa00 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1aa10 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1aa20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1aa30 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1aa40 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1aa50 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1aa60 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1aa70 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1aa80 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1aa90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1aaa0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1aab0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1aac0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1aad0 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1aae0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1aaf0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ab00 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ab10 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ab20 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ab30 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ab40 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ab50 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ab60 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ab70 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ab80 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ab90 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1aba0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1abb0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1abc0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1abd0 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1abe0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1abf0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1ac00 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1ac10 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1ac20 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1ac30 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1ac40 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1ac50 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1ac60 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1ac70 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1ac80 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1ac90 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1aca0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1acb0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1acc0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1acd0 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1ace0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1acf0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1ad00 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1ad10 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1ad20 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1ad30 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1ad40 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1ad50 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1ad60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1ad70 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1ad80 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1ad90 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1ada0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1adb0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1adc0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1add0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1ade0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1adf0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1ae00 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1ae10 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1ae20 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1ae30 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1ae40 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1ae50 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1ae60 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1ae70 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1ae80 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1ae90 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1aea0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1aeb0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1aec0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1aed0 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1aee0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1aef0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1af00 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1af10 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1af20 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1af30 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1af40 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1af50 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1af60 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1af70 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1af80 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1af90 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1afa0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1afb0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1afc0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1afd0 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1afe0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1aff0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1b000 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1b010 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1b020 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1b030 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1b040 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1b050 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1b060 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1b070 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1b080 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1b090 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1b0a0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1b0b0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1b0c0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1b0d0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1b0e0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1b0f0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1b100 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1b110 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b120 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1b130 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1b140 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1b150 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1b160 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1b170 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1b180 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1b190 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1b1a0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1b1b0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1b1c0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1b1d0 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1b1e0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1b1f0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1b200 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1b210 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1b220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1b230 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1b240 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1b250 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1b260 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1b270 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1b280 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1b290 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1b2a0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1b2b0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1b2c0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1b2d0 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1b2e0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1b2f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1b300 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1b310 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1b320 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1b330 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1b340 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1b350 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1b360 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1b370 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1b380 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1b390 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1b3a0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1b3b0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1b3c0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1b3d0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1b3e0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1b3f0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1b400 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1b410 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1b420 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1b430 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1b440 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1b450 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1b460 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1b470 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1b480 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1b490 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1b4a0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1b4b0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1b4c0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1b4d0 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1b4e0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1b4f0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1b500 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1b510 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1b520 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1b530 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1b540 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1b550 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1b560 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1b570 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1b580 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  g()]..*/.int sql
1b590 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1b5a0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1b5b0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1b5c0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1b5d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1b5e0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1b5f0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1b600 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1b610 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1b620 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1b630 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1b640 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1b650 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1b660 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1b670 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1b680 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1b690 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1b6a0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1b6b0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1b6c0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1b6d0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1b6e0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1b6f0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72  .void sqlite3_fr
1b700 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a  ee_table(char **
1b710 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  result);../*.** 
1b720 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74  CAPI3REF: Format
1b730 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74  ted String Print
1b740 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1b750 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1b760 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b  es are work-alik
1b770 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74  es of the "print
1b780 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66  f()" family of f
1b790 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d  unctions.** from
1b7a0 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1b7b0 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73  library..** Thes
1b7c0 65 20 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72  e routines under
1b7d0 73 74 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68  stand most of th
1b7e0 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72  e common K&R for
1b7f0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c  matting options,
1b800 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64  .** plus some ad
1b810 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61  ditional non-sta
1b820 6e 64 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64  ndard formats, d
1b830 65 74 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a  etailed below..*
1b840 2a 20 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65  * Note that some
1b850 20 6f 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73   of the more obs
1b860 63 75 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20  cure formatting 
1b870 6f 70 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63  options from rec
1b880 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79  ent.** C-library
1b890 20 73 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f   standards are o
1b8a0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73  mitted from this
1b8b0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1b8c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1b8d0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e  te3_mprintf() an
1b8e0 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e  d sqlite3_vmprin
1b8f0 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72  tf() routines wr
1b900 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73  ite their.** res
1b910 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  ults into memory
1b920 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
1b930 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1b940 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67  ]..** The string
1b950 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  s returned by th
1b960 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73  ese two routines
1b970 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65   should be.** re
1b980 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74  leased by [sqlit
1b990 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f  e3_free()].  ^Bo
1b9a0 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  th routines retu
1b9b0 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  rn a.** NULL poi
1b9c0 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33  nter if [sqlite3
1b9d0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e  _malloc()] is un
1b9e0 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
1b9f0 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72   enough.** memor
1ba00 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65  y to hold the re
1ba10 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a  sulting string..
1ba20 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
1ba30 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72  te3_snprintf() r
1ba40 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61  outine is simila
1ba50 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29  r to "snprintf()
1ba60 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74  " from.** the st
1ba70 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1ba80 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73  .  The result is
1ba90 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68   written into th
1baa0 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70  e.** buffer supp
1bab0 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  lied as the seco
1bac0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f  nd parameter who
1bad0 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e  se size is given
1bae0 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74   by.** the first
1baf0 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65   parameter. Note
1bb00 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20   that the order 
1bb10 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  of the.** first 
1bb20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69  two parameters i
1bb30 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20  s reversed from 
1bb40 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54  snprintf().)^  T
1bb50 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73  his is an.** his
1bb60 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74  torical accident
1bb70 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20   that cannot be 
1bb80 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72  fixed without br
1bb90 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61  eaking.** backwa
1bba0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1bbb0 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20  y.  ^(Note also 
1bbc0 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70  that sqlite3_snp
1bbd0 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72  rintf().** retur
1bbe0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1bbf0 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65  its buffer inste
1bc00 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  ad of the number
1bc10 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72   of.** character
1bc20 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74  s actually writt
1bc30 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66  en into the buff
1bc40 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20  er.)^  We admit 
1bc50 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  that.** the numb
1bc60 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
1bc70 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62   written would b
1bc80 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20  e a more useful 
1bc90 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
1bca0 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68  but we cannot ch
1bcb0 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ange the impleme
1bcc0 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74  ntation of sqlit
1bcd0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1bce0 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65   now without bre
1bcf0 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c  aking compatibil
1bd00 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c  ity..**.** ^As l
1bd10 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65  ong as the buffe
1bd20 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65  r size is greate
1bd30 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c  r than zero, sql
1bd40 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a  ite3_snprintf().
1bd50 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  ** guarantees th
1bd60 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73  at the buffer is
1bd70 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
1bd80 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66  minated.  ^The f
1bd90 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1bda0 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74  r "n" is the tot
1bdb0 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62  al size of the b
1bdc0 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67  uffer, including
1bdd0 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68   space for.** th
1bde0 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
1bdf0 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65  r.  So the longe
1be00 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63  st string that c
1be10 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79  an be completely
1be20 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c  .** written will
1be30 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65   be n-1 characte
1be40 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  rs..**.** ^The s
1be50 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1be60 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20  () routine is a 
1be70 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20  varargs version 
1be80 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  of sqlite3_snpri
1be90 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ntf()..**.** The
1bea0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20  se routines all 
1beb0 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61  implement some a
1bec0 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74  dditional format
1bed0 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20  ting.** options 
1bee0 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20  that are useful 
1bef0 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67  for constructing
1bf00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
1bf10 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75  .** All of the u
1bf20 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f  sual printf() fo
1bf30 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73  rmatting options
1bf40 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69   apply.  In addi
1bf50 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69  tion, there.** i
1bf60 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22  s are "%q", "%Q"
1bf70 2c 20 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20  , "%w" and "%z" 
1bf80 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1bf90 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1bfa0 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1bfb0 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1bfc0 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1bfd0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1bfe0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1bff0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1c000 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1c010 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1c020 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1c030 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1c040 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1c050 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1c060 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1c070 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1c080 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1c090 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1c0a0 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1c0b0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1c0c0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1c0d0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1c0e0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1c0f0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1c100 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1c110 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1c120 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1c130 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1c140 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1c150 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1c160 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1c170 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1c180 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1c190 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1c1a0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c1b0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c1c0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1c1d0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1c1e0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1c1f0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1c200 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1c210 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1c220 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1c230 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1c240 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1c250 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1c260 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1c270 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1c280 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1c290 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1c2a0 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1c2b0 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1c2c0 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1c2d0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1c2e0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1c2f0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1c300 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1c310 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1c320 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1c330 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1c340 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1c350 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1c360 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1c370 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1c380 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1c390 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1c3a0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1c3b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1c3c0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1c3d0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1c3e0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1c3f0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1c400 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1c410 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1c420 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1c430 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1c440 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1c450 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1c460 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1c470 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1c480 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1c490 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1c4a0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1c4b0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1c4c0 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1c4d0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1c4e0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1c4f0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1c500 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1c510 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1c520 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1c530 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1c540 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1c550 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1c560 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1c570 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1c580 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1c590 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1c5a0 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1c5b0 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1c5c0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1c5d0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1c5e0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1c5f0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1c600 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1c610 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1c620 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1c630 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1c640 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1c650 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1c660 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1c670 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1c680 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1c690 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1c6a0 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1c6b0 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1c6c0 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1c6d0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1c6e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1c6f0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66  .** ^(The "%w" f
1c700 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1c710 20 69 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78   is like "%q" ex
1c720 63 65 70 74 20 74 68 61 74 20 69 74 20 65 78 70  cept that it exp
1c730 65 63 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f  ects to.** be co
1c740 6e 74 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64  ntained within d
1c750 6f 75 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73  ouble-quotes ins
1c760 74 65 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71  tead of single q
1c770 75 6f 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a  uotes, and it.**
1c780 20 65 73 63 61 70 65 73 20 74 68 65 20 64 6f 75   escapes the dou
1c790 62 6c 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63  ble-quote charac
1c7a0 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ter instead of t
1c7b0 68 65 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a  he single-quote.
1c7c0 2a 2a 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20  ** character.)^ 
1c7d0 20 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74   The "%w" format
1c7e0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69  ting option is i
1c7f0 6e 74 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65  ntended for safe
1c800 6c 79 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  ly inserting.** 
1c810 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e  table and column
1c820 20 6e 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f   names into a co
1c830 6e 73 74 72 75 63 74 65 64 20 53 51 4c 20 73 74  nstructed SQL st
1c840 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  atement..**.** ^
1c850 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
1c860 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
1c870 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
1c880 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
1c890 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
1c8a0 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
1c8b0 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
1c8c0 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
1c8d0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
1c8e0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
1c8f0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
1c900 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61  string.)^.*/.cha
1c910 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1c920 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1c930 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1c940 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1c950 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1c960 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1c970 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1c980 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1c990 20 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c   ...);.char *sql
1c9a0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1c9b0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1c9c0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1c9d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c9e0 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1c9f0 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1ca00 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1ca10 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1ca20 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1ca30 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1ca40 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1ca50 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1ca60 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1ca70 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1ca80 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1ca90 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1caa0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1cab0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1cac0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1cad0 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1cae0 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1caf0 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1cb00 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1cb10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cb20 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1cb30 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1cb40 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1cb50 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1cb60 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1cb70 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1cb80 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1cb90 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1cba0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1cbb0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1cbc0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1cbd0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1cbe0 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1cbf0 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1cc00 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1cc10 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1cc20 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1cc30 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1cc40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1cc50 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1cc60 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
1cc70 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1cc80 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
1cc90 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
1cca0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ccb0 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1ccc0 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
1ccd0 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
1cce0 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
1ccf0 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
1cd00 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
1cd10 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
1cd20 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
1cd30 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
1cd40 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1cd50 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1cd60 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1cd70 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
1cd80 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
1cd90 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
1cda0 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
1cdb0 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
1cdc0 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
1cdd0 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
1cde0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
1cdf0 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
1ce00 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
1ce10 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
1ce20 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
1ce30 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
1ce40 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
1ce50 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
1ce60 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
1ce70 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
1ce80 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
1ce90 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
1cea0 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
1ceb0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
1cec0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1ced0 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
1cee0 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
1cef0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
1cf00 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
1cf10 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
1cf20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
1cf30 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
1cf40 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
1cf50 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
1cf60 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
1cf70 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1cf80 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1cf90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1cfa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1cfb0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
1cfc0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1cfd0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1cfe0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1cff0 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
1d000 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1d010 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
1d020 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1d030 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1d040 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
1d050 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1d060 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1d070 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1d080 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1d090 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
1d0a0 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
1d0b0 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1d0c0 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
1d0d0 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1d0e0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1d0f0 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1d100 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1d110 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
1d120 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1d130 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
1d140 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1d150 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
1d160 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
1d170 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
1d180 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
1d190 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
1d1a0 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
1d1b0 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
1d1c0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
1d1d0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
1d1e0 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
1d1f0 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
1d200 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
1d210 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
1d220 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
1d230 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
1d240 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
1d250 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
1d260 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1d270 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
1d280 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
1d290 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
1d2a0 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
1d2b0 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
1d2c0 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
1d2d0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
1d2e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
1d2f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
1d300 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
1d310 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
1d320 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
1d330 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
1d340 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
1d350 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
1d360 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
1d370 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
1d380 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
1d390 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
1d3a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1d3b0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
1d3c0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
1d3d0 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
1d3e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
1d3f0 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
1d400 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
1d410 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
1d420 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1d430 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
1d440 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
1d450 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1d460 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
1d470 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1d480 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
1d490 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
1d4a0 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
1d4b0 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
1d4c0 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
1d4d0 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
1d4e0 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
1d4f0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
1d500 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1d510 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
1d520 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
1d530 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
1d540 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
1d550 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
1d560 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
1d570 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
1d580 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
1d590 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
1d5a0 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
1d5b0 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
1d5c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1d5d0 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
1d5e0 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
1d5f0 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
1d600 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
1d610 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1d620 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1d630 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
1d640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
1d650 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1d660 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
1d670 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
1d680 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
1d690 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
1d6a0 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
1d6b0 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
1d6c0 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
1d6d0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
1d6e0 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
1d6f0 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
1d700 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
1d710 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
1d720 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
1d730 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
1d740 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
1d750 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
1d760 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
1d770 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
1d780 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
1d790 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
1d7a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
1d7b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
1d7c0 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
1d7d0 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
1d7e0 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
1d7f0 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
1d800 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1d810 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
1d820 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
1d830 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
1d840 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
1d850 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
1d860 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
1d870 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
1d880 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
1d890 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
1d8a0 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
1d8b0 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
1d8c0 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
1d8d0 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
1d8e0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
1d8f0 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
1d900 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
1d910 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
1d920 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
1d930 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
1d940 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
1d950 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
1d960 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
1d970 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
1d980 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
1d990 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
1d9a0 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
1d9b0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1d9c0 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
1d9d0 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
1d9e0 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
1d9f0 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
1da00 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1da10 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
1da20 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
1da30 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
1da40 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
1da50 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
1da60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1da70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1da80 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
1da90 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
1daa0 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
1dab0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1dac0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
1dad0 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
1dae0 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
1daf0 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
1db00 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
1db10 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
1db20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1db30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1db40 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64  lloc()]..*/.void
1db50 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
1db60 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c  (int);.void *sql
1db70 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71  ite3_malloc64(sq
1db80 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76  lite3_uint64);.v
1db90 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1dba0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1dbb0 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1dbc0 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1dbd0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1dbe0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1dbf0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69  ree(void*);.sqli
1dc00 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  te3_uint64 sqlit
1dc10 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b  e3_msize(void*);
1dc20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1dc30 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1dc40 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
1dc50 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
1dc60 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
1dc70 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
1dc80 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
1dc90 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
1dca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1dcb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
1dcc0 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
1dcd0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
1dce0 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
1dcf0 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
1dd00 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1dd10 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
1dd20 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
1dd30 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1dd40 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1dd50 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1dd60 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
1dd70 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
1dd80 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
1dd90 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
1dda0 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
1ddb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ddc0 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
1ddd0 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
1dde0 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
1ddf0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1de00 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
1de10 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
1de20 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
1de30 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
1de40 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
1de50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1de60 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
1de70 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1de80 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
1de90 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
1dea0 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
1deb0 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
1dec0 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
1ded0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
1dee0 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
1def0 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
1df00 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
1df10 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
1df20 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
1df30 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1df40 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
1df50 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
1df60 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
1df70 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
1df80 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
1df90 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
1dfa0 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
1dfb0 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
1dfc0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
1dfd0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
1dfe0 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
1dff0 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
1e000 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
1e010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1e020 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
1e030 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1e040 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
1e050 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c  he reset..*/.sql
1e060 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1e070 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
1e080 6f 69 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  oid);.sqlite3_in
1e090 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1e0a0 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1e0b0 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1e0c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1e0d0 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1e0e0 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1e0f0 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1e100 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1e110 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1e120 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1e130 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1e140 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1e150 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1e160 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1e170 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1e180 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1e190 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1e1a0 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1e1b0 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1e1c0 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1e1d0 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1e1e0 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1e1f0 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1e200 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1e210 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1e220 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1e230 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1e240 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1e250 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
1e260 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
1e270 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
1e280 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
1e290 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
1e2a0 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
1e2b0 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
1e2c0 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
1e2d0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1e2e0 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
1e2f0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
1e300 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
1e310 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
1e320 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
1e330 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
1e340 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1e350 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
1e360 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
1e370 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1e380 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
1e390 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1e3a0 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
1e3b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1e3c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1e3d0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1e3e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1e3f0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1e400 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
1e410 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
1e420 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
1e430 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
1e440 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
1e450 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
1e460 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
1e470 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
1e480 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
1e490 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69  * method..*/.voi
1e4a0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
1e4b0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
1e4c0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
1e4d0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
1e4e0 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
1e4f0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d  n Callbacks.** M
1e500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1e510 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1e520 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1e530 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e540 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1e550 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1e560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1e570 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1e580 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1e590 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1e5a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1e5b0 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1e5c0 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1e5d0 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1e5e0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1e5f0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1e600 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1e610 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1e620 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1e630 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1e640 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1e650 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1e660 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1e670 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1e680 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1e690 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1e6a0 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1e6b0 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1e6c0 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1e6d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e6e0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1e6f0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1e700 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1e710 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1e720 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1e730 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1e740 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1e750 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1e760 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1e770 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1e780 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1e790 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1e7a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1e7b0 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1e7c0 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1e7d0 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1e7e0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1e7f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1e800 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1e810 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1e820 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1e830 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1e840 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1e850 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1e860 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1e870 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1e880 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1e890 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1e8a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1e8b0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1e8c0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1e8d0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1e8e0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1e8f0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1e900 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1e910 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1e920 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1e930 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1e940 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1e950 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1e960 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1e970 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e980 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1e990 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e9a0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1e9b0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1e9c0 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1e9d0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1e9e0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1e9f0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1ea00 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1ea10 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1ea20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1ea30 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1ea40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1ea50 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1ea60 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1ea70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ea80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ea90 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1eaa0 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1eab0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1eac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1ead0 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1eae0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1eaf0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1eb00 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1eb10 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1eb20 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1eb30 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1eb40 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1eb50 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1eb60 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1eb70 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1eb80 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1eb90 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1eba0 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1ebb0 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1ebc0 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1ebd0 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1ebe0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1ebf0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1ec00 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1ec10 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1ec20 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1ec30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ec40 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1ec50 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1ec60 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1ec70 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1ec80 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1ec90 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1eca0 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1ecb0 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1ecc0 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1ecd0 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1ece0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1ecf0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1ed00 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1ed10 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1ed20 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1ed30 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1ed40 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1ed50 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1ed60 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1ed70 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1ed80 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1ed90 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1eda0 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1edb0 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1edc0 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1edd0 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1ede0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1edf0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1ee00 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1ee10 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1ee20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1ee30 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1ee40 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1ee50 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1ee60 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1ee70 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1ee80 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1ee90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1eea0 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1eeb0 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1eec0 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1eed0 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1eee0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1eef0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1ef00 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1ef10 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1ef20 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1ef30 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1ef40 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1ef50 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1ef60 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1ef70 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1ef80 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1ef90 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1efa0 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1efb0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1efc0 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1efd0 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1efe0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1eff0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1f000 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1f010 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1f020 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1f030 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1f040 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1f050 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1f060 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1f070 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1f080 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1f090 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1f0a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1f0b0 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1f0c0 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1f0d0 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1f0e0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1f0f0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1f100 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1f110 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1f120 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1f130 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1f140 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1f150 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1f160 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1f170 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1f180 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1f190 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1f1a0 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1f1b0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1f1c0 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1f1d0 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1f1e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f1f0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1f200 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1f210 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1f220 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1f230 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1f240 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1f250 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1f260 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1f270 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1f280 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1f290 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1f2a0 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1f2b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f2c0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1f2d0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1f2e0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1f2f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1f300 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1f310 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1f320 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1f330 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1f340 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1f350 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1f360 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1f370 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1f380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1f390 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1f3a0 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1f3b0 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1f3c0 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1f3d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1f3e0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1f3f0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1f400 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1f410 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1f420 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1f430 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f440 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1f450 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1f460 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1f470 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1f480 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1f490 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1f4a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1f4b0 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1f4c0 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1f4d0 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1f4e0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1f4f0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1f500 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1f510 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1f520 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1f530 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1f540 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1f550 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1f560 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1f570 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1f580 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1f590 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1f5a0 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1f5b0 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1f5c0 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1f5d0 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1f5e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1f5f0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1f600 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1f610 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1f620 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1f630 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1f640 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1f650 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1f660 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1f670 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1f680 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1f690 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1f6a0 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1f6b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1f6c0 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1f6d0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1f6e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1f6f0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1f700 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1f710 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1f720 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1f730 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1f740 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1f750 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1f760 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1f770 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1f780 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1f790 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1f7a0 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1f7b0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1f7c0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1f7d0 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1f7e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1f7f0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1f800 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1f810 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1f820 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
1f830 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
1f840 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
1f850 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
1f860 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
1f870 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
1f880 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
1f890 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
1f8a0 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
1f8b0 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
1f8c0 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
1f8d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
1f8e0 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
1f8f0 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
1f900 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
1f910 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
1f920 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1f930 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
1f940 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1f950 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1f960 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
1f970 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
1f980 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1f990 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
1f9a0 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
1f9b0 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
1f9c0 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
1f9d0 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
1f9e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1f9f0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1fa00 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
1fa10 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
1fa20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
1fa30 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
1fa40 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
1fa50 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
1fa60 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
1fa70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fa80 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
1fa90 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
1faa0 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
1fab0 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
1fac0 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
1fad0 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
1fae0 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
1faf0 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
1fb00 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
1fb10 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
1fb20 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1fb30 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
1fb40 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
1fb50 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
1fb60 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
1fb70 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
1fb80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1fb90 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
1fba0 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
1fbb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fbc0 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
1fbd0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
1fbe0 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
1fbf0 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
1fc00 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
1fc10 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
1fc20 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
1fc30 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
1fc40 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1fc50 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
1fc60 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
1fc70 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1fc80 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
1fc90 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
1fca0 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
1fcb0 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
1fcc0 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
1fcd0 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
1fce0 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1fcf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fd00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
1fd10 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
1fd20 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
1fd30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1fd40 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
1fd50 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
1fd60 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1fd70 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1fd80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1fd90 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
1fda0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
1fdb0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1fdc0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1fdd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1fde0 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
1fdf0 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
1fe00 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
1fe10 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1fe20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1fe30 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
1fe40 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
1fe50 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1fe60 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1fe70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1fe80 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
1fe90 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
1fea0 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1feb0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1fec0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1fed0 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
1fee0 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
1fef0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1ff00 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1ff10 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ff20 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
1ff30 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
1ff40 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
1ff50 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ff60 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ff70 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
1ff80 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
1ff90 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ffa0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ffb0 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
1ffc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
1ffd0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1ffe0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1fff0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
20000 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
20010 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
20020 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
20030 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
20040 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
20050 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
20060 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
20070 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
20080 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
20090 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
200a0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
200b0 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
200c0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
200d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
200e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
200f0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
20100 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
20110 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20120 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
20130 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20140 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
20150 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
20160 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
20170 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20190 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
201a0 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
201b0 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
201c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
201d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
201e0 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
201f0 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
20200 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
20210 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
20220 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20230 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
20240 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
20250 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
20260 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
20270 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20280 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
20290 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
202a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le 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 50  #define SQLITE_P
202d0 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
202e0 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
202f0 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
20300 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
20310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
20320 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
20330 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
20340 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
20350 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
20360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
20370 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
20380 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
20390 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            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 54 52 41 4e  fine SQLITE_TRAN
203c0 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
203d0 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
203e0 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
203f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
20400 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
20410 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
20420 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
20430 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
20440 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
20450 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
20460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
20470 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
20480 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
20490 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
204a0 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
204b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
204c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
204d0 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   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 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
20500 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
20510 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
20520 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   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 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
20550 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
20560 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index 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 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
205a0 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
205b0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
205c0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
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 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
205f0 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
20600 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
20610 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
20620 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
20630 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
20640 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
20650 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
20660 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
20670 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
20680 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
20690 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
206a0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
206b0 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
206c0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
206d0 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
206e0 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
206f0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
20700 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
20710 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
20720 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
20730 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
20740 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
20750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
20760 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
20770 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
20780 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
20790 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
207a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
207b0 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
207c0 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
207d0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
207e0 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
207f0 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
20800 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20810 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
20820 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
20830 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
20840 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
20850 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
20860 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
20870 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
20880 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
20890 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
208a0 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
208b0 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
208c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
208d0 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
208e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
208f0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
20900 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
20910 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
20920 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
20930 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
20940 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
20950 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
20960 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
20970 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
20980 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
20990 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
209a0 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
209b0 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
209c0 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
209d0 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
209e0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
209f0 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
20a00 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
20a10 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
20a20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
20a30 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
20a40 54 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  The [SQLITE_TRAC
20a50 45 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f  E_SIZE_LIMIT] co
20a60 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
20a70 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20a80 20 6c 69 6d 69 74 0a 2a 2a 20 74 68 65 20 6c 65   limit.** the le
20a90 6e 67 74 68 20 6f 66 20 5b 62 6f 75 6e 64 20 70  ngth of [bound p
20aa0 61 72 61 6d 65 74 65 72 5d 20 65 78 70 61 6e 73  arameter] expans
20ab0 69 6f 6e 20 69 6e 20 74 68 65 20 6f 75 74 70 75  ion in the outpu
20ac0 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 74 72 61  t of sqlite3_tra
20ad0 63 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ce()..**.** ^The
20ae0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
20af0 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
20b00 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
20b10 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
20b20 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
20b30 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
20b40 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
20b50 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
20b60 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
20b70 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
20b80 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
20b90 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
20ba0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
20bb0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
20bc0 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
20bd0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
20be0 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
20bf0 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
20c00 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
20c10 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
20c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
20c30 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
20c40 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
20c50 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
20c60 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
20c70 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
20c80 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
20c90 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
20ca0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
20cb0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
20cc0 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
20cd0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
20ce0 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
20cf0 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
20d00 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
20d10 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
20d20 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
20d30 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
20d40 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
20d50 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
20d60 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
20d70 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74  .void *sqlite3_t
20d80 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
20d90 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
20da0 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
20db0 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
20dc0 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69  EXPERIMENTAL voi
20dd0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
20de0 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
20df0 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
20e00 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
20e10 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
20e20 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
20e30 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
20e40 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
20e50 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
20e60 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
20e70 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
20e80 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
20e90 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
20ea0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
20eb0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
20ec0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
20ed0 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
20ee0 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
20ef0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
20f00 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
20f10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
20f20 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
20f30 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
20f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
20f50 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
20f60 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
20f70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
20f80 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
20f90 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
20fa0 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
20fb0 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
20fc0 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
20fd0 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
20fe0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20ff0 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
21000 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
21010 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
21020 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
21030 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
21040 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
21050 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
21060 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
21070 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
21080 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
21090 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
210a0 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
210b0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
210c0 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
210d0 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
210e0 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
210f0 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
21100 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
21110 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
21120 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
21130 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21140 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
21150 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
21160 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
21170 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
21180 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
21190 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
211a0 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
211b0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
211c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
211d0 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
211e0 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
211f0 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
21200 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
21210 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
21220 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
21230 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
21240 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
21250 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
21260 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
21270 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
21280 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
21290 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
212a0 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
212b0 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
212c0 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
212d0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
212e0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
212f0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
21300 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
21310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
21320 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
21330 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
21340 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
21350 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21360 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
21370 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
21380 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
21390 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
213a0 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
213b0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
213c0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
213d0 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71  h..**.*/.void sq
213e0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
213f0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
21400 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
21410 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
21420 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
21430 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
21440 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
21450 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
21460 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
21470 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
21480 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
21490 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
214a0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
214b0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
214c0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
214d0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
214e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
214f0 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
21500 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
21510 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21520 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
21530 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
21540 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
21550 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
21560 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
21570 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21580 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
21590 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
215a0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
215b0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
215c0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
215d0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
215e0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
215f0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
21600 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
21610 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
21620 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
21630 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
21640 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
21650 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
21660 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
21670 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
21680 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
21690 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
216a0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
216b0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
216c0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
216d0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
216e0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
216f0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
21700 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
21710 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
21720 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
21730 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
21740 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
21750 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
21760 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
21770 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
21780 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
21790 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
217a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
217b0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
217c0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
217d0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
217e0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
217f0 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
21800 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
21810 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
21820 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
21830 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
21840 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
21850 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
21860 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
21870 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
21880 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
21890 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
218a0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
218b0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
218c0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
218d0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
218e0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
218f0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
21900 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
21910 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
21920 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
21930 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
21940 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
21950 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
21960 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
21970 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
21980 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
21990 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
219a0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
219b0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
219c0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
219d0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
219e0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
219f0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
21a00 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
21a10 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
21a20 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
21a30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
21a40 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
21a50 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
21a60 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
21a70 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
21a80 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
21a90 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
21aa0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
21ab0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
21ac0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
21ad0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
21ae0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
21af0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21b00 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
21b10 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21b20 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
21b30 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
21b40 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
21b50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
21b60 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
21b70 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
21b80 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
21b90 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
21ba0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
21bb0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
21bc0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
21bd0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
21be0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21bf0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
21c00 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
21c10 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
21c20 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
21c30 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
21c40 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
21c50 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
21c60 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
21c70 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21c80 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
21c90 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
21ca0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
21cb0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
21cc0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
21cd0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
21ce0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
21cf0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
21d00 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
21d10 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
21d20 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
21d30 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21d40 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
21d50 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
21d60 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
21d70 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
21d80 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
21d90 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
21da0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
21db0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
21dc0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
21dd0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
21de0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
21df0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
21e00 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
21e10 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
21e20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
21e30 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
21e40 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
21e50 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
21e60 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
21e70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
21e80 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
21e90 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
21ea0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
21eb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
21ec0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
21ed0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
21ee0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
21ef0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
21f00 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
21f10 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
21f20 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
21f30 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
21f40 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
21f50 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
21f60 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
21f70 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
21f80 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
21f90 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
21fa0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
21fb0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
21fc0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
21fd0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
21fe0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
21ff0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
22000 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
22010 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
22020 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
22030 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
22040 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
22050 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
22060 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
22070 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
22080 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
22090 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
220a0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
220b0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
220c0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
220d0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
220e0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
220f0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
22100 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
22110 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
22120 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
22130 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
22140 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
22150 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
22160 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22170 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
22180 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
22190 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
221a0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
221b0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
221c0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
221d0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
221e0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
221f0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
22200 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
22210 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
22220 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
22230 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
22240 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
22250 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22260 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
22270 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
22280 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
22290 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
222a0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
222b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
222c0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
222d0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
222e0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
222f0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
22300 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
22310 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
22320 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
22330 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
22340 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
22350 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
22360 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
22370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22380 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
22390 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
223a0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
223b0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
223c0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
223d0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
223e0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
223f0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
22400 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
22410 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
22420 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
22430 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
22440 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
22450 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
22460 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
22470 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
22480 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
22490 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
224a0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
224b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
224c0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
224d0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
224e0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
224f0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
22500 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
22510 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
22520 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
22530 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
22540 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
22550 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
22560 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
22570 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
22580 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
22590 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
225a0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
225b0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
225c0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
225d0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
225e0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
225f0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
22600 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
22610 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
22620 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
22630 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
22640 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22650 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
22660 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
22670 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
22680 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
22690 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
226a0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
226b0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
226c0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
226d0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
226e0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
226f0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
22700 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
22710 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
22720 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
22730 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
22740 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
22750 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
22760 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
22770 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
22780 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22790 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
227a0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
227b0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
227c0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
227d0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
227e0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
227f0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
22800 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
22810 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
22820 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
22830 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
22840 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22850 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22860 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
22870 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
22880 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
22890 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
228a0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
228b0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
228c0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
228d0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
228e0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
228f0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
22900 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
22910 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
22920 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
22930 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
22940 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
22950 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
22960 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
22970 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
22980 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
22990 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
229a0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
229b0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
229c0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
229d0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
229e0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
229f0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
22a00 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
22a10 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
22a20 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
22a30 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
22a40 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
22a50 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
22a60 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
22a70 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
22a80 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
22a90 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
22aa0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
22ab0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
22ac0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
22ad0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
22ae0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
22af0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
22b00 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
22b10 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
22b20 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
22b30 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
22b40 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
22b50 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
22b60 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
22b70 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
22b80 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
22b90 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
22ba0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
22bb0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
22bc0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
22bd0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
22be0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
22bf0 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
22c00 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
22c10 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
22c20 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
22c30 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
22c40 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
22c50 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
22c60 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
22c70 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
22c80 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
22c90 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
22ca0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
22cb0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
22cc0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
22cd0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
22ce0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
22cf0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
22d00 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
22d10 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
22d20 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
22d30 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
22d40 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
22d50 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
22d60 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
22d70 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
22d80 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
22d90 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
22da0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
22db0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
22dc0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
22dd0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
22de0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
22df0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
22e00 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
22e10 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
22e20 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
22e30 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
22e40 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
22e50 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
22e60 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
22e70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
22e80 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
22e90 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
22ea0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
22eb0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22ec0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22ed0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
22ee0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
22ef0 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
22f00 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
22f10 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
22f20 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
22f30 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
22f40 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
22f50 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
22f60 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22f70 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
22f80 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
22f90 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
22fa0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
22fb0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
22fc0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
22fd0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
22fe0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
22ff0 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
23000 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
23010 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
23020 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
23030 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
23040 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
23050 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
23060 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
23070 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
23080 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
23090 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
230a0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
230b0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
230c0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
230d0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
230e0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
230f0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
23100 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
23110 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
23120 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
23130 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
23140 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
23150 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
23160 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
23170 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
23180 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
23190 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
231a0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
231b0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
231c0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
231d0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
231e0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
231f0 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
23200 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
23210 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
23220 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
23230 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
23240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
23250 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
23260 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
23270 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
23280 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
23290 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
232a0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
232b0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
232c0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
232d0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
232e0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
232f0 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
23300 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23310 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
23320 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
23330 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
23340 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
23350 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
23360 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
23370 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
23380 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
23390 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
233a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
233b0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
233c0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
233d0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
233e0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
233f0 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
23400 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
23410 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
23420 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
23430 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
23440 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
23450 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
23460 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
23470 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
23480 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
23490 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
234a0 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
234b0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
234c0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
234d0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
234e0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
234f0 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
23500 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
23510 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
23520 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
23530 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
23540 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
23550 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
23560 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
23570 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
23580 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
23590 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
235a0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
235b0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
235c0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
235d0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
235e0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
235f0 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
23600 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
23610 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
23620 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
23630 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
23640 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
23650 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
23660 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
23670 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
23680 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
23690 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
236a0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
236b0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
236c0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
236d0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
236e0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
236f0 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
23700 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
23710 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
23720 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
23730 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
23740 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
23750 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
23760 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
23770 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
23780 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
23790 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
237a0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
237b0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
237c0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
237d0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
237e0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
237f0 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
23800 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
23810 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
23820 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
23830 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23840 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
23850 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
23860 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
23870 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
23880 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
23890 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
238a0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
238b0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
238c0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
238d0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
238e0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
238f0 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
23900 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
23910 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
23920 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
23930 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
23940 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
23950 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
23960 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
23970 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
23980 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
23990 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
239a0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
239b0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
239c0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
239d0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
239e0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
239f0 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
23a00 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23a10 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
23a20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
23a30 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
23a40 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
23a50 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
23a60 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
23a70 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
23a80 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
23a90 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
23aa0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
23ab0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
23ac0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
23ad0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
23ae0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
23af0 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
23b00 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
23b10 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
23b20 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
23b30 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
23b40 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
23b50 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
23b60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23b70 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
23b80 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
23b90 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
23ba0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
23bb0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
23bc0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
23bd0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
23be0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
23bf0 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
23c00 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
23c10 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
23c20 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
23c30 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
23c40 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
23c50 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
23c60 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
23c70 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
23c80 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
23c90 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
23ca0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
23cb0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
23cc0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
23cd0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
23ce0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
23cf0 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
23d00 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
23d10 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
23d20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
23d30 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
23d40 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
23d50 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
23d60 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
23d70 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
23d80 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
23d90 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
23da0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
23db0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
23dc0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
23dd0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
23de0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
23df0 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
23e00 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
23e10 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
23e20 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
23e30 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
23e40 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
23e50 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
23e60 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
23e70 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
23e80 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
23e90 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
23ea0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
23eb0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
23ec0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
23ed0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
23ee0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
23ef0 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
23f00 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
23f10 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
23f20 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
23f30 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
23f40 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
23f50 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
23f60 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
23f70 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
23f80 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
23f90 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
23fa0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
23fb0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
23fc0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
23fd0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23fe0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
23ff0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
24000 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
24010 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
24020 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
24030 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
24040 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
24050 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
24060 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
24070 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
24080 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
24090 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
240a0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
240b0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
240c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
240d0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
240e0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
240f0 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
24100 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
24110 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
24120 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
24130 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
24140 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
24150 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
24160 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
24170 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
24180 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
24190 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
241a0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
241b0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
241c0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
241d0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
241e0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
241f0 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
24200 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
24210 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
24220 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
24230 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
24240 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
24250 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
24260 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
24270 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
24280 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
24290 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
242a0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
242b0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
242c0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
242d0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
242e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
242f0 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
24300 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
24310 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
24320 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
24330 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
24340 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
24350 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
24360 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
24370 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
24380 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
24390 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
243a0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
243b0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
243c0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
243d0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
243e0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
243f0 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
24400 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
24410 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
24420 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
24430 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
24440 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
24450 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
24460 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
24470 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
24480 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
24490 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
244a0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
244b0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
244c0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
244d0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
244e0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
244f0 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
24500 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
24510 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
24520 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
24530 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24540 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
24550 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
24560 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
24570 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
24580 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
24590 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
245a0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
245b0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
245c0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
245d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
245e0 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
245f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
24600 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
24610 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
24620 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
24630 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
24640 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
24650 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
24660 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
24670 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
24680 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
24690 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
246a0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
246b0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
246c0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
246d0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
246e0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
246f0 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
24700 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
24710 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
24720 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
24730 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
24740 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
24750 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
24760 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
24770 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
24780 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
24790 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
247a0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
247b0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
247c0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
247d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
247e0 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
247f0 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24800 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
24810 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
24820 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
24830 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
24840 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
24850 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
24860 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
24870 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
24880 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
24890 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
248a0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
248b0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
248c0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
248d0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
248e0 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
248f0 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
24900 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
24910 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
24920 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
24930 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
24940 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
24950 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24960 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
24970 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
24980 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
24990 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
249a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
249b0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
249c0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
249d0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
249e0 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
249f0 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
24a00 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
24a10 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
24a20 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
24a30 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
24a40 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
24a50 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
24a60 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
24a70 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
24a80 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
24a90 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
24aa0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
24ab0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
24ac0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
24ad0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
24ae0 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
24af0 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
24b00 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
24b10 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
24b20 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
24b30 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
24b40 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
24b50 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24b60 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
24b70 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
24b80 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
24b90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
24ba0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
24bb0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
24bc0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
24bd0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
24be0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
24bf0 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
24c00 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
24c10 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
24c20 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
24c30 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
24c40 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
24c50 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
24c60 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
24c70 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
24c80 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
24c90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
24ca0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
24cb0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
24cc0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
24cd0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
24ce0 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
24cf0 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
24d00 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
24d10 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
24d20 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
24d30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
24d40 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
24d50 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
24d60 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
24d70 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
24d80 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
24d90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
24da0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
24db0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
24dc0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
24dd0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
24de0 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
24df0 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
24e00 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
24e10 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
24e20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
24e30 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
24e40 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
24e50 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
24e60 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
24e70 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
24e80 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
24e90 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
24ea0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
24eb0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
24ec0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24ed0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24ee0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
24ef0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
24f00 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
24f10 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
24f20 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
24f30 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
24f40 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24f50 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
24f60 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
24f70 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
24f80 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
24f90 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
24fa0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
24fb0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
24fc0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
24fd0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
24fe0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
24ff0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
25000 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
25010 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
25020 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
25030 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
25040 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
25050 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
25060 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
25070 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
25080 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
25090 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
250a0 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
250b0 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
250c0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
250d0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
250e0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
250f0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
25100 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
25110 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
25120 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
25130 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
25140 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
25150 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
25160 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
25170 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
25180 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
25190 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
251a0 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
251b0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
251c0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
251d0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
251e0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
251f0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
25200 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
25210 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
25220 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
25230 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
25240 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
25250 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
25260 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
25270 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
25280 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
25290 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
252a0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
252b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
252c0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
252d0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
252e0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
252f0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
25300 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
25310 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
25320 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
25330 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
25340 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
25350 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
25360 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
25370 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
25380 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
25390 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
253a0 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
253b0 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
253c0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
253d0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
253e0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
253f0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
25400 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
25410 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
25420 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
25430 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
25440 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
25450 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
25460 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
25470 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
25480 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
25490 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
254a0 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
254b0 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
254c0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
254d0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
254e0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
254f0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
25500 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
25510 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
25520 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
25530 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
25540 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
25550 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
25560 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
25570 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
25580 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
25590 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
255a0 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
255b0 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
255c0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
255d0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
255e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
255f0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
25600 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
25610 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
25620 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
25630 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
25640 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
25650 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
25660 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
25670 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
25680 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
25690 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
256a0 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
256b0 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
256c0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
256d0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
256e0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
256f0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
25700 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
25710 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
25720 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
25730 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
25740 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
25750 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
25760 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
25770 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
25780 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  set..*/.int sqli
25790 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
257a0 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71  te3 *db);.int sq
257b0 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
257c0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
257d0 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  db);.const char 
257e0 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  *sqlite3_errmsg(
257f0 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74  sqlite3*);.const
25800 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65   void *sqlite3_e
25810 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a  rrmsg16(sqlite3*
25820 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
25830 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e  qlite3_errstr(in
25840 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
25850 52 45 46 3a 20 50 72 65 70 61 72 65 64 20 53 74  REF: Prepared St
25860 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
25870 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
25880 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
25890 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
258a0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
258b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
258c0 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
258d0 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
258e0 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a  statement that.*
258f0 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69  * has been compi
25900 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20  led into binary 
25910 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64  form and is read
25920 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  y to be evaluate
25930 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f  d..**.** Think o
25940 66 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  f each SQL state
25950 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61 72 61  ment as a separa
25960 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67  te computer prog
25970 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69  ram.  The.** ori
25980 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69  ginal SQL text i
25990 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20  s source code.  
259a0 41 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  A prepared state
259b0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20  ment object .** 
259c0 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20  is the compiled 
259d0 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c  object code.  Al
259e0 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f  l SQL must be co
259f0 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a  nverted into a.*
25a00 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
25a10 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63  ment before it c
25a20 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a  an be run..**.**
25a30 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20   The life-cycle 
25a40 6f 66 20 61 20 70 72 65 70 61 72 65 64 20 73 74  of a prepared st
25a50 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25a60 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65  sually goes like
25a70 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
25a80 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
25a90 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25aa0 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75  atement object u
25ab0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
25ac0 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20  epare_v2()]..** 
25ad0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
25ae0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d   to [parameters]
25af0 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
25b00 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
25b10 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
25b20 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
25b30 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
25b40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25b50 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
25b60 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
25b70 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25b80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
25b90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
25ba0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
25bb0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
25bc0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
25bd0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
25be0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
25bf0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
25c00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
25c10 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  )]..** </ol>.*/.
25c20 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
25c30 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
25c40 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
25c50 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
25c60 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45  ime Limits.** ME
25c70 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
25c80 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
25c90 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
25ca0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
25cb0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
25cc0 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
25cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
25ce0 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
25cf0 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
25d00 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
25d10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25d20 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
25d30 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
25d40 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
25d50 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
25d60 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
25d70 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
25d80 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
25d90 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
25da0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
25db0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
25dc0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
25dd0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
25de0 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
25df0 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
25e00 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
25e10 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
25e20 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
25e30 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
25e40 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
25e50 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
25e60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
25e70 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
25e80 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
25e90 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
25ea0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
25eb0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
25ec0 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
25ed0 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
25ee0 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
25ef0 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
25f00 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
25f10 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
25f20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
25f30 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
25f40 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
25f50 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
25f60 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
25f70 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
25f80 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
25f90 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
25fa0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
25fb0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
25fc0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
25fd0 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
25fe0 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
25ff0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
26000 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26010 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
26020 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
26030 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
26040 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
26050 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
26060 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
26070 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
26080 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
26090 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
260a0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
260b0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
260c0 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
260d0 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
260e0 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
260f0 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
26100 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
26110 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
26120 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
26130 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
26140 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
26150 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
26160 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
26170 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
26180 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
26190 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
261a0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
261b0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
261c0 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
261d0 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
261e0 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
261f0 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
26200 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
26210 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
26220 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
26230 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26240 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
26250 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
26260 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
26270 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
26280 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
26290 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
262a0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
262b0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
262c0 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
262d0 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
262e0 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
262f0 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
26300 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
26310 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
26320 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
26330 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
26340 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
26350 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
26360 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
26370 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
26380 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
26390 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
263a0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
263b0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
263c0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
263d0 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
263e0 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
263f0 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
26400 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
26410 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73  leases..*/.int s
26420 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
26430 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
26440 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
26450 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
26460 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
26470 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
26480 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
26490 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
264a0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
264b0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
264c0 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
264d0 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
264e0 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
264f0 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
26500 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
26510 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
26520 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
26530 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
26540 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
26550 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
26560 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
26570 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
26580 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
26590 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
265a0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
265b0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
265c0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
265d0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
265e0 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
265f0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
26600 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
26610 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
26620 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
26630 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
26640 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26650 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
26660 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26670 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
26680 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26690 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
266a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
266b0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
266c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
266d0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
266e0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
266f0 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
26700 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26710 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
26720 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
26730 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
26740 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
26750 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
26760 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
26770 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
26780 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
26790 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
267a0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
267b0 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
267c0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
267d0 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
267e0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
267f0 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
26800 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26810 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
26820 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
26830 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
26840 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
26850 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
26860 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
26870 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
26880 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
26890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
268a0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
268b0 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
268c0 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
268d0 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
268e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
268f0 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
26900 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
26910 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
26920 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
26930 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
26940 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
26950 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
26960 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
26970 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
26980 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
26990 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
269a0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
269b0 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
269c0 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
269d0 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
269e0 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
269f0 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
26a00 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
26a10 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
26a20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26a30 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
26a40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
26a50 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
26a60 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
26a70 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
26a80 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26a90 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
26aa0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
26ab0 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
26ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
26ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
26ae0 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
26af0 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
26b00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
26b10 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
26b20 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
26b30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
26b40 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
26b50 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
26b60 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
26b70 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
26b80 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
26b90 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
26ba0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
26bb0 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
26bc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
26bd0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
26be0 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
26bf0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
26c00 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
26c10 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
26c20 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
26c30 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
26c40 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
26c50 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
26c60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
26c70 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
26c80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
26c90 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
26ca0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26cb0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
26cc0 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
26cd0 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
26ce0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
26cf0 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
26d00 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EADS]] ^(<dt>SQL
26d10 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
26d20 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a  _THREADS</dt>.**
26d30 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
26d40 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78 69 6c   number of auxil
26d50 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68 72 65  iary worker thre
26d60 61 64 73 20 74 68 61 74 20 61 20 73 69 6e 67 6c  ads that a singl
26d70 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
26d80 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20 73 74  tatement] may st
26d90 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  art.</dd>)^.** <
26da0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
26db0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
26dc0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
26dd0 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
26de0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
26df0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
26e00 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
26e10 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
26e20 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
26e30 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
26e40 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
26e50 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
26e60 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
26e70 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
26e80 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
26e90 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
26ea0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
26eb0 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
26ec0 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
26ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
26ee0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
26ef0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
26f00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
26f10 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
26f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
26f30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
26f40 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
26f50 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
26f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
26f70 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
26f80 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
26f90 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
26fa0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
26fb0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
26fc0 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
26fd0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
26fe0 48 52 45 41 44 53 20 20 20 20 20 20 20 20 20 20  HREADS          
26ff0 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   11../*.** CAPI3
27000 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41  REF: Compiling A
27010 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
27020 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51  ** KEYWORDS: {SQ
27030 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
27040 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  iler}.** METHOD:
27050 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f 4e 53   sqlite3.** CONS
27060 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
27070 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65  _stmt.**.** To e
27080 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75  xecute an SQL qu
27090 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72  ery, it must fir
270a0 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69  st be compiled i
270b0 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a  nto a byte-code.
270c0 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67  ** program using
270d0 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f   one of these ro
270e0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
270f0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
27100 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61  , "db", is a [da
27110 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27120 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  n] obtained from
27130 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63   a.** prior succ
27140 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b  essful call to [
27150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
27160 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
27170 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  2()] or.** [sqli
27180 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20  te3_open16()].  
27190 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  The database con
271a0 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  nection must not
271b0 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65   have been close
271c0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  d..**.** The sec
271d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a  ond argument, "z
271e0 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61  Sql", is the sta
271f0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
27200 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a  piled, encoded.*
27210 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d  * as either UTF-
27220 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68  8 or UTF-16.  Th
27230 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
27240 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
27250 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20  prepare_v2().** 
27260 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55  interfaces use U
27270 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65  TF-8, and sqlite
27280 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e  3_prepare16() an
27290 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
272a0 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20  e16_v2().** use 
272b0 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49  UTF-16..**.** ^I
272c0 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75  f the nByte argu
272d0 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69 76 65  ment is negative
272e0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
272f0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
27300 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
27310 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
27320 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  e is positive, t
27330 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a 2a 2a  hen it is the.**
27340 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
27350 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e   read from zSql.
27360 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 7a    ^If nByte is z
27370 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70 72 65  ero, then no pre
27380 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
27390 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65 64 2e  nt is generated.
273a0 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c 6c 65  .** If the calle
273b0 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74 68 65  r knows that the
273c0 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67   supplied string
273d0 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74   is nul-terminat
273e0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 72  ed, then.** ther
273f0 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70 65 72  e is a small per
27400 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61  formance advanta
27410 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20 61 6e  ge to passing an
27420 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
27430 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68 65 20   that.** is the 
27440 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27450 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  in the input str
27460 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67  ing <i>including
27470 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d  </i>.** the nul-
27480 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a  terminator..**.*
27490 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
274a0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
274b0 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
274c0 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
274d0 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
274e0 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
274f0 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
27500 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
27510 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
27520 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
27530 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
27540 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
27550 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
27560 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
27570 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
27580 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
27590 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
275a0 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
275b0 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
275c0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
275d0 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
275e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
275f0 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
27600 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
27610 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
27620 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
27630 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
27640 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
27650 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
27660 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
27670 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
27680 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
27690 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
276a0 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
276b0 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
276c0 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
276d0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
276e0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
276f0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27700 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
27710 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
27720 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
27730 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
27740 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
27750 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
27760 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
27770 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
27780 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
27790 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
277a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
277b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
277c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
277d0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
277e0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
277f0 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
27800 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
27810 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
27820 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
27830 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
27840 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
27850 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
27860 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
27870 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
27880 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
27890 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
278a0 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
278b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
278c0 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
278d0 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
278e0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
278f0 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
27900 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
27910 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
27920 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
27930 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
27940 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
27950 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
27960 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
27970 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
27980 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
27990 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
279a0 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
279b0 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
279c0 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
279d0 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
279e0 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
279f0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
27a00 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
27a10 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
27a20 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
27a30 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
27a40 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
27a50 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
27a60 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
27a70 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
27a80 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
27a90 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
27aa0 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
27ab0 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
27ac0 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
27ad0 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
27ae0 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
27af0 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
27b00 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
27b10 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
27b20 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
27b30 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
27b40 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
27b50 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
27b60 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
27b70 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
27b80 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
27b90 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
27ba0 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
27bb0 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
27bc0 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
27bd0 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
27be0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
27bf0 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
27c00 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
27c10 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
27c20 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
27c30 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
27c40 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
27c50 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
27c60 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
27c70 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
27c80 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
27c90 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
27ca0 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
27cb0 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
27cc0 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
27cd0 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
27ce0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
27cf0 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
27d00 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
27d10 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
27d20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
27d30 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
27d40 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
27d50 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
27d60 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
27d70 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
27d80 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
27d90 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
27da0 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
27db0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
27dc0 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
27dd0 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
27de0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
27df0 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
27e00 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
27e10 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
27e20 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
27e30 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
27e40 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
27e50 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
27e60 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
27e70 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
27e80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
27e90 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
27ea0 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
27eb0 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
27ec0 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
27ed0 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
27ee0 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
27ef0 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
27f00 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
27f10 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
27f20 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
27f30 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
27f40 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
27f50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
27f60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27f70 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27f80 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27f90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
27fa0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27fb0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
27fc0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
27fd0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
27fe0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
27ff0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28000 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28010 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28020 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28030 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28040 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28050 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28060 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28070 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28080 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
28090 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
280a0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
280b0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
280c0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
280d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
280e0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
280f0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
28100 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
28110 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
28120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
28130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
28140 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
28150 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
28160 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
28170 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
28180 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
28190 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
281a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
281b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
281c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
281d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
281e0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
281f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28200 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28210 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28220 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
28230 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28240 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
28250 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
28260 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
28270 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28280 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28290 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
282a0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
282b0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
282c0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
282d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
282e0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
282f0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28300 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28310 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
28320 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28330 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
28340 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28350 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28360 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28370 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28380 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28390 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
283a0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
283b0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
283c0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
283d0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
283e0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
283f0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28400 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28410 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28420 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
28430 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28440 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28450 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28470 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
28480 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d  atement SQL.** M
28490 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
284a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  tmt.**.** ^This 
284b0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
284c0 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
284d0 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
284e0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
284f0 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
28500 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
28510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28520 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
28530 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
28540 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
28550 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28560 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
28570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28580 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  )]..*/.const cha
28590 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
285a0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
285b0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
285c0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
285d0 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
285e0 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
285f0 61 74 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f  atabase.** METHO
28600 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
28610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
28620 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
28630 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
28640 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
28650 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
28660 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
28670 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28680 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
28690 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
286a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
286b0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
286c0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
286d0 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
286e0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
286f0 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
28700 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
28710 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
28720 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
28730 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
28740 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
28750 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
28760 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
28770 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
28780 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
28790 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
287a0 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
287b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
287c0 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
287d0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
287e0 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
287f0 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
28800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
28810 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
28820 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
28830 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
28840 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
28850 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
28860 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
28870 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
28880 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
28890 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
288a0 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
288b0 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
288c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
288d0 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
288e0 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
288f0 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
28900 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
28910 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
28920 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
28930 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
28940 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
28950 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
28960 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
28970 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
28980 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
28990 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
289a0 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
289b0 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
289c0 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
289d0 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
289e0 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
289f0 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
28a00 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
28a10 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
28a20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
28a30 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
28a40 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
28a50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
28a60 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
28a70 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
28a80 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
28a90 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
28aa0 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
28ab0 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
28ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
28ad0 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
28ae0 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
28af0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
28b00 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28b10 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
28b20 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
28b30 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
28b40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
28b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
28b60 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
28b70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
28b80 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
28b90 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
28ba0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
28bb0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
28bc0 62 75 73 79 28 53 29 20 69 6e 74 65 72 66 61 63  busy(S) interfac
28bd0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
28be0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65  non-zero) if the
28bf0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28c00 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62  atement] S has b
28c10 65 65 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c  een stepped at l
28c20 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20  east once using 
28c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28c40 70 28 53 29 5d 20 62 75 74 20 68 61 73 20 6e 65  p(S)] but has ne
28c50 69 74 68 65 72 20 72 75 6e 20 74 6f 20 63 6f 6d  ither run to com
28c60 70 6c 65 74 69 6f 6e 20 28 72 65 74 75 72 6e 65  pletion (returne
28c70 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  d.** [SQLITE_DON
28c80 45 5d 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  E] from [sqlite3
28c90 5f 73 74 65 70 28 53 29 5d 29 20 6e 6f 72 0a 2a  _step(S)]) nor.*
28ca0 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69  * been reset usi
28cb0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
28cc0 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c  t(S)].  ^The sql
28cd0 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
28ce0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
28cf0 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20  eturns false if 
28d00 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  S is a NULL poin
28d10 74 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f  ter.  If S is no
28d20 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  t a .** NULL poi
28d30 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20  nter and is not 
28d40 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
28d50 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73  alid [prepared s
28d60 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
28d70 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ect, then the be
28d80 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
28d90 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
28da0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a   undesirable..**
28db0 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
28dc0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ce can be used i
28dd0 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73  n combination [s
28de0 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74  qlite3_next_stmt
28df0 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65  ()].** to locate
28e00 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74   all prepared st
28e10 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61  atements associa
28e20 74 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62  ted with a datab
28e30 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  ase .** connecti
28e40 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e  on that are in n
28e50 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73  eed of being res
28e60 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65  et.  This can be
28e70 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78   used,.** for ex
28e80 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f  ample, in diagno
28e90 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f  stic routines to
28ea0 20 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70   search for prep
28eb0 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65  ared .** stateme
28ec0 6e 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c  nts that are hol
28ed0 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69  ding a transacti
28ee0 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20  on open..*/.int 
28ef0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
28f00 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  y(sqlite3_stmt*)
28f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28f20 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54  F: Dynamically T
28f30 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63  yped Value Objec
28f40 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
28f50 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
28f60 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74  3_value} {unprot
28f70 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
28f80 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  lue}.**.** SQLit
28f90 65 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74  e uses the sqlit
28fa0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
28fb0 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c  to represent all
28fc0 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20   values.** that 
28fd0 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e  can be stored in
28fe0 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
28ff0 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64  e. SQLite uses d
29000 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a  ynamic typing.**
29010 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20   for the values 
29020 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c  it stores.  ^Val
29030 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71  ues stored in sq
29040 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29050 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e  cts.** can be in
29060 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67  tegers, floating
29070 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73   point values, s
29080 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f  trings, BLOBs, o
29090 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e  r NULL..**.** An
290a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
290b0 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74  bject may be eit
290c0 68 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20  her "protected" 
290d0 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  or "unprotected"
290e0 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66  ..** Some interf
290f0 61 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70  aces require a p
29100 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
29110 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69  _value.  Other i
29120 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c  nterfaces.** wil
29130 6c 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20  l accept either 
29140 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61  a protected or a
29150 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
29160 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20  lite3_value..** 
29170 45 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20  Every interface 
29180 74 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c  that accepts sql
29190 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d  ite3_value argum
291a0 65 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a  ents specifies.*
291b0 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * whether or not
291c0 20 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70   it requires a p
291d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
291e0 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20  _value.  The.** 
291f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64  [sqlite3_value_d
29200 75 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  up()] interface 
29210 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
29220 6f 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a  onstruct a new .
29230 2a 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  ** protected sql
29240 69 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20  ite3_value from 
29250 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
29260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
29270 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
29280 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
29290 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
292a0 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
292b0 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
292c0 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
292d0 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
292e0 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
292f0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
29300 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
29310 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
29320 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
29330 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
29340 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
29350 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
29360 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
29370 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
29380 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
29390 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
293a0 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
293b0 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
293c0 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
293d0 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
293e0 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
293f0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
29400 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
29410 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
29420 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
29430 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
29440 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
29450 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
29460 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
29470 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
29480 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29490 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
294a0 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
294b0 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
294c0 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
294d0 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
294e0 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
294f0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
29500 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
29510 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
29520 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
29530 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
29540 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
29550 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29560 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
29570 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
29580 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
29590 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
295a0 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
295b0 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
295c0 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
295d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
295e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
295f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
29600 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
29610 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
29620 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29630 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
29640 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
29650 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
29660 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
29670 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29680 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
29690 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
296a0 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
296b0 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
296c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
296d0 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
296e0 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
296f0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
29700 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
29710 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
29720 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
29730 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
29740 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
29750 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
29760 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
29770 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
29780 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
29790 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
297a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
297b0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
297c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
297d0 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
297e0 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
297f0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
29800 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
29810 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
29820 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
29830 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
29840 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
29850 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
29860 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
29870 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
29880 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
29890 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
298a0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
298b0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
298c0 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
298d0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
298e0 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
298f0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
29900 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
29910 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
29920 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
29930 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
29940 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
29950 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
29960 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
29970 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
29980 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
29990 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
299a0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
299b0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
299c0 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
299d0 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
299e0 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
299f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
29a00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
29a10 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
29a20 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
29a30 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
29a40 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
29a50 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
29a60 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
29a70 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
29a80 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
29a90 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
29aa0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
29ab0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
29ac0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
29ad0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
29ae0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
29af0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
29b00 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
29b10 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
29b20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
29b30 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
29b40 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
29b50 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
29b60 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
29b70 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
29b80 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
29b90 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
29ba0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
29bb0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
29bc0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
29bd0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
29be0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
29bf0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
29c00 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
29c10 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
29c20 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
29c30 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
29c40 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
29c50 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
29c60 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
29c70 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
29c80 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
29c90 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
29ca0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
29cb0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
29cc0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
29cd0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
29ce0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
29cf0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
29d00 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
29d10 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
29d20 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
29d30 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
29d40 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
29d50 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
29d60 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
29d70 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
29d80 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
29d90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
29da0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
29db0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
29dc0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
29dd0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
29de0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
29df0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
29e00 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
29e10 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
29e20 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
29e30 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
29e40 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
29e50 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
29e60 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
29e70 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
29e80 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
29e90 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
29ea0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
29eb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29ec0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
29ed0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
29ee0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
29ef0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
29f00 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
29f10 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
29f20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
29f30 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
29f40 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
29f50 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
29f60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
29f70 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
29f80 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
29f90 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
29fa0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
29fb0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
29fc0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
29fd0 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
29fe0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
29ff0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2a000 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2a010 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2a020 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2a030 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
2a040 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
2a050 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2a060 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
2a070 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
2a080 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
2a090 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
2a0a0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
2a0b0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
2a0c0 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
2a0d0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2a0e0 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
2a0f0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2a100 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
2a110 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
2a120 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
2a130 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2a140 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
2a150 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
2a160 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
2a170 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
2a180 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
2a190 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2a1a0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2a1b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2a1c0 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
2a1d0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2a1e0 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
2a1f0 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
2a200 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2a210 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
2a220 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
2a230 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
2a240 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2a250 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
2a260 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
2a270 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
2a280 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2a290 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
2a2a0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2a2b0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2a2c0 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2a2d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2a2e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2a2f0 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
2a300 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2a310 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
2a320 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2a330 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2a340 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2a350 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2a360 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2a370 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2a380 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2a390 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2a3a0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2a3b0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2a3c0 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2a3d0 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2a3e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2a3f0 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2a400 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2a410 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2a420 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2a430 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2a440 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2a450 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2a460 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2a470 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2a480 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2a490 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2a4a0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
2a4b0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
2a4c0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
2a4d0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2a4e0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2a4f0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2a500 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2a510 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2a520 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2a530 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2a540 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2a550 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2a560 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2a570 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
2a580 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
2a590 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2a5a0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2a5b0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2a5c0 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2a5d0 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2a5e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2a5f0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2a600 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2a610 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2a620 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2a630 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2a640 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2a650 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2a660 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2a670 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2a680 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2a690 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2a6a0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2a6b0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2a6c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2a6d0 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2a6e0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2a6f0 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2a700 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2a710 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
2a720 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
2a730 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
2a740 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
2a750 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
2a760 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
2a770 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
2a780 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
2a790 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
2a7a0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
2a7b0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
2a7c0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
2a7d0 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2a7e0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
2a7f0 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
2a800 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
2a810 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
2a820 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
2a830 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
2a840 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
2a850 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
2a860 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
2a870 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
2a880 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
2a890 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a8a0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2a8b0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2a8c0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2a8d0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2a8e0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2a8f0 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2a900 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2a910 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2a920 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2a930 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2a940 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2a950 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2a960 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2a970 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2a980 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2a990 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2a9a0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2a9b0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2a9c0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2a9d0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2a9e0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2a9f0 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2aa00 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2aa10 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2aa20 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2aa30 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2aa40 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2aa50 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2aa60 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2aa70 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2aa80 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2aa90 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2aaa0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2aab0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2aac0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2aad0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2aae0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2aaf0 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2ab00 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2ab10 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2ab20 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2ab30 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2ab40 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2ab50 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2ab60 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2ab70 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2ab80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ab90 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2aba0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2abb0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2abc0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2abd0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2abe0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2abf0 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2ac00 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2ac10 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2ac20 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2ac30 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2ac40 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2ac50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ac60 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2ac70 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2ac80 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2ac90 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2aca0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2acb0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2acc0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
2acd0 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
2ace0 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
2acf0 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
2ad00 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
2ad10 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
2ad20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2ad30 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2ad40 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
2ad50 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
2ad60 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
2ad70 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
2ad80 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
2ad90 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
2ada0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
2adb0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
2adc0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
2add0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
2ade0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2adf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2ae00 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2ae10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2ae20 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2ae30 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
2ae40 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2ae50 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2ae60 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
2ae70 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
2ae80 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2ae90 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
2aea0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
2aeb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2aec0 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2aed0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
2aee0 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69  oid*, sqlite3_ui
2aef0 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20  nt64,.          
2af00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2af10 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
2af20 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2af30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2af40 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
2af50 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  e);.int sqlite3_
2af60 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
2af70 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
2af80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2af90 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ind_int64(sqlite
2afa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
2afb0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e  lite3_int64);.in
2afc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2afd0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2afe0 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c  *, int);.int sql
2aff0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
2b000 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b010 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
2b020 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2b030 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
2b040 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2b050 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b060 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2b070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b080 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
2b090 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74 65 33  d_text64(sqlite3
2b0a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2b0b0 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65  st char*, sqlite
2b0c0 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20 20  3_uint64,.      
2b0d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b0e0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2b0f0 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72  ), unsigned char
2b100 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 69 6e 74 20   encoding);.int 
2b110 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b120 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2b130 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2b140 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2b150 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2b160 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2b170 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2b180 6e 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  n);.int sqlite3_
2b190 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 36 34 28  bind_zeroblob64(
2b1a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2b1b0 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  nt, sqlite3_uint
2b1c0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
2b1d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2b1e0 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  SQL Parameters.*
2b1f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2b200 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2b210 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
2b220 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
2b230 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
2b240 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
2b250 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
2b260 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
2b270 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2b280 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
2b290 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
2b2a0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
2b2b0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
2b2c0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
2b2d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
2b2e0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
2b2f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b300 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
2b310 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
2b320 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
2b330 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
2b340 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
2b350 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
2b360 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
2b370 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
2b380 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
2b390 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
2b3a0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
2b3b0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
2b3c0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
2b3d0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
2b3e0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
2b3f0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
2b400 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
2b410 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
2b420 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
2b430 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b440 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b450 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2b460 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b470 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2b480 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
2b490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b4a0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2b4b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2b4c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b4d0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2b4e0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2b4f0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
2b500 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
2b510 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b520 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b530 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2b540 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e  rameter_name(P,N
2b550 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b560 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20  rns.** the name 
2b570 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c  of the N-th [SQL
2b580 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2b590 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2b5a0 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28  tement] P..** ^(
2b5b0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f  SQL parameters o
2b5c0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e  f the form "?NNN
2b5d0 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2b5e0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2b5f0 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77  ** have a name w
2b600 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69  hich is the stri
2b610 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  ng "?NNN" or ":A
2b620 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2b630 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65   "$AAA".** respe
2b640 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f  ctively..** In o
2b650 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2b660 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22  initial ":" or "
2b670 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22  $" or "@" or "?"
2b680 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20  .** is included 
2b690 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e  as part of the n
2b6a0 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d  ame.)^.** ^Param
2b6b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2b6c0 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20  m "?" without a 
2b6d0 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65  following intege
2b6e0 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a  r have no name.*
2b6f0 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72  * and are referr
2b700 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65  ed to as "namele
2b710 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75  ss" or "anonymou
2b720 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a  s parameters"..*
2b730 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2b740 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68  host parameter h
2b750 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2b760 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  , not 0..**.** ^
2b770 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69  If the value N i
2b780 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f  s out of range o
2b790 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61  r if the N-th pa
2b7a0 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61  rameter is.** na
2b7b0 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c  meless, then NUL
2b7c0 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  L is returned.  
2b7d0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2b7e0 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79  ring is.** alway
2b7f0 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64  s in UTF-8 encod
2b800 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20  ing even if the 
2b810 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20  named parameter 
2b820 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c  was.** originall
2b830 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55  y specified as U
2b840 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65  TF-16 in [sqlite
2b850 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f  3_prepare16()] o
2b860 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
2b870 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2b880 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2b890 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b8a0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2b8b0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2b8c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2b8d0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2b8e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b8f0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2b900 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2b910 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b920 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2b930 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2b940 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b950 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2b960 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2b970 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
2b980 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2b990 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2b9a0 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2b9b0 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2b9c0 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2b9d0 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2b9e0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2b9f0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2ba00 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2ba10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2ba20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2ba30 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2ba40 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2ba50 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2ba60 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2ba70 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2ba80 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2ba90 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2baa0 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2bab0 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2bac0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2bad0 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2bae0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2baf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bb00 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2bb10 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2bb20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2bb30 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2bb40 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2bb50 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2bb60 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2bb70 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bb80 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2bb90 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2bba0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2bbb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2bbc0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2bbd0 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2bbe0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2bbf0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2bc00 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2bc10 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bc20 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43  e3_stmt.**.** ^C
2bc30 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2bc40 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2bc50 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2bc60 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2bc70 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2bc80 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2bc90 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2bca0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bcb0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2bcc0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2bcd0 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2bce0 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2bcf0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
2bd00 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2bd10 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2bd20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2bd30 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2bd40 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2bd50 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2bd60 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2bd70 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2bd80 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2bd90 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2bda0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2bdb0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2bdc0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2bdd0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2bde0 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2bdf0 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2be00 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2be10 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2be20 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2be30 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2be40 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2be50 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2be60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2be70 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2be80 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2be90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2bea0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2beb0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2bec0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2bed0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2bee0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2bef0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2bf00 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2bf10 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2bf20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2bf30 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2bf40 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2bf50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2bf60 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2bf70 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2bf80 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2bf90 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2bfa0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2bfb0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2bfc0 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2bfd0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2bfe0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2bff0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2c000 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2c010 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2c020 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c030 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2c040 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2c050 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2c060 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2c070 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2c080 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2c090 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2c0a0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2c0b0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2c0c0 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2c0d0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2c0e0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2c0f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2c100 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2c110 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c120 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2c130 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2c140 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2c150 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2c160 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2c170 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c180 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2c190 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2c1a0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2c1b0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2c1c0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2c1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2c1e0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2c1f0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2c200 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2c210 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2c220 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2c230 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2c240 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2c250 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2c260 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2c270 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2c280 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2c290 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2c2a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2c2b0 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2c2c0 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2c2d0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2c2e0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2c2f0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2c300 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2c310 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2c320 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2c330 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2c340 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2c350 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2c360 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2c370 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2c380 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2c390 65 78 74 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ext..*/.const ch
2c3a0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c3b0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2c3c0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 63  stmt*, int N);.c
2c3d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2c3e0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2c3f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c400 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
2c410 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
2c420 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
2c430 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
2c440 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2c450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2c460 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2c470 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2c480 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2c490 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2c4a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2c4b0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2c4c0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2c4d0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2c4e0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2c4f0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2c500 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2c510 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2c520 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2c530 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2c540 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2c550 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2c560 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2c570 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c580 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2c590 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2c5a0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2c5b0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2c5c0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2c5d0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2c5e0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2c5f0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2c600 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c610 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2c620 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2c630 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2c640 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2c650 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c660 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2c670 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2c680 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2c690 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2c6a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2c6b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2c6c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2c6d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2c6e0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2c6f0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2c700 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2c710 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2c720 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2c730 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2c740 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2c750 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2c760 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2c770 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2c780 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2c790 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2c7a0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2c7b0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2c7c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c7d0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2c7e0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2c7f0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2c800 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2c810 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2c820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2c830 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2c840 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2c850 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2c860 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2c870 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2c880 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2c890 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c8a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2c8b0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2c8c0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2c8d0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2c8e0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2c8f0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2c900 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2c910 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2c920 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2c930 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2c940 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2c950 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2c960 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2c970 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2c980 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2c990 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2c9a0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2c9b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2c9c0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2c9d0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2c9e0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2c9f0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2ca00 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2ca10 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2ca20 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2ca30 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2ca40 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2ca50 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2ca60 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2ca70 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2ca80 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2ca90 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2caa0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2cab0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2cac0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2cad0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2cae0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2caf0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2cb00 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2cb10 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2cb20 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2cb30 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2cb40 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2cb50 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2cb60 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cb70 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2cb80 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2cb90 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2cba0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2cbb0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2cbc0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2cbd0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2cbe0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2cbf0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2cc00 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2cc10 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2cc20 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2cc30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cc40 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2cc50 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2cc60 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2cc70 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2cc80 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2cc90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2cca0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2ccb0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2ccc0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2ccd0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2cce0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2ccf0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2cd00 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2cd10 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2cd20 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2cd30 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2cd40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2cd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2cd60 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2cd70 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2cd80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2cd90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2cda0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2cdb0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2cdc0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2cdd0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2cde0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2cdf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ce00 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2ce10 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2ce20 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2ce30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2ce40 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2ce50 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ce60 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2ce70 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2ce80 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2ce90 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2cea0 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2ceb0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2cec0 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2ced0 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2cee0 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2cef0 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2cf00 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2cf10 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2cf20 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2cf30 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2cf40 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2cf50 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2cf60 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2cf70 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2cf80 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2cf90 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2cfa0 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2cfb0 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2cfc0 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2cfd0 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2cfe0 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2cff0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2d000 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2d010 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2d020 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2d030 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2d040 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2d050 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2d060 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2d070 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2d080 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2d090 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2d0a0 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2d0b0 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2d0c0 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2d0d0 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2d0e0 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2d0f0 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2d100 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2d110 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2d120 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2d130 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2d140 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2d150 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2d160 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2d170 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2d180 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2d190 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2d1a0 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2d1b0 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2d1c0 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2d1d0 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2d1e0 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2d1f0 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2d200 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2d210 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2d220 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2d230 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2d240 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2d250 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2d260 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2d270 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2d280 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2d290 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 63 6f 6e 73   values..*/.cons
2d2a0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d2b0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2d2c0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d2d0 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  t);.const void *
2d2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d2f0 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65  ecltype16(sqlite
2d300 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f  3_stmt*,int);../
2d310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
2d320 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53  valuate An SQL S
2d330 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48  tatement.** METH
2d340 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2d350 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2d360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d370 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2d380 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2d390 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2d3a0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d3b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d3c0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2d3d0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2d3e0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2d3f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2d400 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d410 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2d420 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2d430 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2d440 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2d450 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2d460 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2d470 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2d480 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2d490 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2d4a0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2d4b0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2d4c0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2d4d0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2d4e0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2d4f0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2d500 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2d510 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2d520 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2d530 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2d540 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2d550 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d560 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2d570 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2d580 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2d590 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2d5a0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2d5b0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2d5c0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2d5d0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2d5e0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2d5f0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2d600 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2d610 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2d620 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2d630 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2d640 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2d650 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2d660 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2d670 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2d680 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2d690 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2d6a0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2d6b0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2d6c0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2d6d0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2d6e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2d6f0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2d700 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2d710 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2d720 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2d730 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2d740 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2d750 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2d760 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2d770 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2d780 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2d790 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2d7a0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2d7b0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2d7c0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2d7d0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2d7e0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2d7f0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2d800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2d810 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2d820 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2d830 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2d840 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2d850 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2d860 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2d870 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2d880 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2d890 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2d8a0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2d8b0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2d8c0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2d8d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2d8e0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2d8f0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2d900 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2d910 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2d920 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2d930 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2d940 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2d950 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2d960 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2d970 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2d980 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2d990 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2d9a0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2d9b0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2d9c0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2d9d0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2d9e0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2d9f0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2da00 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2da10 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2da20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2da30 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2da40 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2da50 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2da60 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2da70 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2da80 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2da90 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2daa0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2dab0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2dac0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2dad0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2dae0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2daf0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2db00 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2db10 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2db20 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2db30 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2db40 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2db50 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2db60 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2db70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2db80 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2db90 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2dba0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2dbb0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2dbc0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2dbd0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2dbe0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2dbf0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2dc00 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2dc10 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2dc20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2dc30 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2dc40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2dc50 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2dc60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2dc70 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2dc80 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2dc90 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2dca0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2dcb0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2dcc0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2dcd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2dce0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2dcf0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2dd00 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2dd10 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2dd20 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2dd30 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2dd40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2dd50 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2dd60 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2dd70 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2dd80 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2dd90 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2dda0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2ddb0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2ddc0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2ddd0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2dde0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2ddf0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2de00 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2de10 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2de20 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2de30 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2de40 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2de50 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2de60 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2de70 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2de80 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2de90 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2dea0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2deb0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2dec0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2ded0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2dee0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2def0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2df00 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2df10 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2df20 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2df30 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2df40 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2df50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2df60 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2df70 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2df80 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2df90 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2dfa0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2dfb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2dfc0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2dfd0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2dfe0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2dff0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2e000 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2e010 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2e020 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2e030 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2e040 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2e050 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2e060 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2e070 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2e080 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2e090 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2e0a0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2e0b0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2e0c0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2e0d0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2e0e0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2e0f0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2e100 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2e110 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2e120 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2e130 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2e140 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2e150 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2e160 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2e170 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e180 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2e190 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2e1a0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2e1b0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2e1c0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2e1d0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2e1e0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2e1f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2e200 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2e210 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2e220 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2e230 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2e240 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2e250 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2e260 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2e270 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2e280 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2e290 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2e2a0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2e2b0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2e2c0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2e2d0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2e2e0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2e2f0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2e300 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2e310 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2e320 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2e330 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2e340 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2e350 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2e360 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2e370 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2e380 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2e390 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2e3a0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2e3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e3c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2e3d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2e3e0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2e3f0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2e400 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2e410 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2e420 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2e430 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2e440 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2e450 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2e460 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2e470 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2e480 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2e490 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2e4a0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54  esult set.** MET
2e4b0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2e4c0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2e4d0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2e4e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e4f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2e500 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2e510 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77  e.** current row
2e520 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2e530 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  et of [prepared 
2e540 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
2e550 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74   ^If prepared st
2e560 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e  atement P does n
2e570 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20  ot have results 
2e580 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a  ready to return.
2e590 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f  ** (via calls to
2e5a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
2e5b0 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74  lumn_int | sqlit
2e5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f  e3_column_*()] o
2e5d0 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29  f.** interfaces)
2e5e0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61   then sqlite3_da
2e5f0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75  ta_count(P) retu
2e600 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73  rns 0..** ^The s
2e610 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e620 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73  t(P) routine als
2e630 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50  o returns 0 if P
2e640 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2e650 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  er..** ^The sqli
2e660 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2e670 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2e680 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69  s 0 if the previ
2e690 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ous call to.** [
2e6a0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2e6b0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2e6c0 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73  E_DONE].  ^The s
2e6d0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2e6e0 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74  t(P).** will ret
2e6f0 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20  urn non-zero if 
2e700 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
2e710 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28   [sqlite3_step](
2e720 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  P) returned.** [
2e730 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63  SQLITE_ROW], exc
2e740 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20  ept in the case 
2e750 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69  of the [PRAGMA i
2e760 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75  ncremental_vacuu
2e770 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61  m].** where it a
2e780 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65  lways returns ze
2e790 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74  ro since each st
2e7a0 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69  ep of that multi
2e7b0 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20  -step.** pragma 
2e7c0 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e  returns 0 column
2e7d0 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  s of data..**.**
2e7e0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2e7f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
2e800 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
2e810 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
2e820 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e830 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e840 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
2e850 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
2e860 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
2e870 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
2e880 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
2e890 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
2e8a0 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
2e8b0 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
2e8c0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
2e8d0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2e8e0 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
2e8f0 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
2e900 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
2e910 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
2e920 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
2e930 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
2e940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2e950 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
2e960 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
2e970 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
2e980 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
2e990 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
2e9a0 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
2e9b0 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
2e9c0 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
2e9d0 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
2e9e0 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
2e9f0 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
2ea00 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
2ea10 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
2ea20 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
2ea30 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
2ea40 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
2ea50 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
2ea60 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
2ea70 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
2ea80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
2ea90 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
2eaa0 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
2eab0 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
2eac0 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
2ead0 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
2eae0 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2eaf0 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
2eb00 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
2eb10 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
2eb20 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
2eb30 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
2eb40 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
2eb50 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
2eb60 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
2eb70 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
2eb80 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45  functions}.** ME
2eb90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2eba0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2ebb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2ebc0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2ebd0 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d  t a single colum
2ebe0 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
2ebf0 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f  .** result row o
2ec00 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20  f a query.  ^In 
2ec10 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66  every case the f
2ec20 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
2ec30 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
2ec40 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2ec50 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69  tatement] that i
2ec60 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65  s being evaluate
2ec70 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2ec80 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77  stmt*].** that w
2ec90 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  as returned from
2eca0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ecb0 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  e_v2()] or one o
2ecc0 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a  f its variants).
2ecd0 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ** and the secon
2ece0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ecf0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63  e index of the c
2ed00 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20  olumn for which 
2ed10 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73  information.** s
2ed20 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
2ed30 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  d. ^The leftmost
2ed40 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2ed50 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68  esult set has th
2ed60 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54  e index 0..** ^T
2ed70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ed80 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75  umns in the resu
2ed90 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  lt can be determ
2eda0 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
2edb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2edc0 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  unt()]..**.** If
2edd0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ede0 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72  nt does not curr
2edf0 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61  ently point to a
2ee00 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69   valid row, or i
2ee10 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  f the.** column 
2ee20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20  index is out of 
2ee30 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c  range, the resul
2ee40 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  t is undefined..
2ee50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2ee60 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61  s may only be ca
2ee70 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f  lled when the mo
2ee80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2ee90 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2eea0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2eeb0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
2eec0 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b  and neither.** [
2eed0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2eee0 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69   nor [sqlite3_fi
2eef0 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62  nalize()] have b
2ef00 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65  een called subse
2ef10 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61  quently..** If a
2ef20 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2ef30 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
2ef40 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72  after [sqlite3_r
2ef50 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2ef60 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ef70 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c  )] or after [sql
2ef80 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ef90 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d   returned.** som
2efa0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
2efb0 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  n [SQLITE_ROW], 
2efc0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2efd0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2efe0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2eff0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
2f000 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
2f010 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a  e3_finalize()].*
2f020 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  * are called fro
2f030 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68  m a different th
2f040 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f  read while any o
2f050 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f060 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c  .** are pending,
2f070 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2f080 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2f090 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f0a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2f0b0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2f0c0 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
2f0d0 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
2f0e0 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ype code] for th
2f0f0 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74  e initial data t
2f100 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65  ype.** of the re
2f110 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54  sult column.  ^T
2f120 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75  he returned valu
2f130 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  e is one of [SQL
2f140 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a  ITE_INTEGER],.**
2f150 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c   [SQLITE_FLOAT],
2f160 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20   [SQLITE_TEXT], 
2f170 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f  [SQLITE_BLOB], o
2f180 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e  r [SQLITE_NULL].
2f190 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72    The value.** r
2f1a0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2f1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f1c0 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67   is only meaning
2f1d0 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a  ful if no type.*
2f1e0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61  * conversions ha
2f1f0 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64  ve occurred as d
2f200 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20  escribed below. 
2f210 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f   After a type co
2f220 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65  nversion,.** the
2f230 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
2f240 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2f250 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65  n_type() is unde
2f260 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a  fined.  Future.*
2f270 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  * versions of SQ
2f280 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20  Lite may change 
2f290 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2f2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f2b0 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  ype().** followi
2f2c0 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  ng a type conver
2f2d0 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  sion..**.** ^If 
2f2e0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2f2f0 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74  BLOB or UTF-8 st
2f300 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71  ring then the sq
2f310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f320 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  es().** routine 
2f330 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2f340 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2f350 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2f360 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2f370 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31  esult is a UTF-1
2f380 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  6 string, then s
2f390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f3a0 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  tes() converts.*
2f3b0 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2f3c0 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72  UTF-8 and then r
2f3d0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f3e0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2f3f0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f400 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2f410 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2f420 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65  lumn_bytes() use
2f430 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2f440 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2f450 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2f460 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  to a UTF-8 strin
2f470 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2f480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2f490 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2f4a0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2f4b0 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2f4c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f4d0 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75  umn_bytes() retu
2f4e0 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
2f4f0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2f500 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2f510 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  16 string then t
2f520 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f530 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72  n_bytes16().** r
2f540 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2f550 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f560 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2f570 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2f580 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f590 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20  a UTF-8 string, 
2f5a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f5b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f  umn_bytes16() co
2f5c0 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2f5d0 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61  ring to UTF-16 a
2f5e0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2f5f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f600 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2f610 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2f620 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2f630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2f640 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20  tes16() uses.** 
2f650 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
2f660 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20  f()] to convert 
2f670 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20  that value to a 
2f680 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e  UTF-16 string an
2f690 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
2f6a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2f6b0 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
2f6c0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2f6d0 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
2f6e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f6f0 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e  bytes16() return
2f700 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s zero..**.** ^T
2f710 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
2f720 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f730 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
2f740 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f750 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f760 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65  ] do not include
2f770 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e   the zero termin
2f780 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64  ators at the end
2f790 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e  .** of the strin
2f7a0 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79  g.  ^For clarity
2f7b0 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74  : the values ret
2f7c0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2f7d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f7e0 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  s()] and [sqlite
2f7f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f800 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62  ()] are the numb
2f810 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69  er of.** bytes i
2f820 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f  n the string, no
2f830 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f840 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a  characters..**.*
2f850 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72  * ^Strings retur
2f860 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2f870 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64  olumn_text() and
2f880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f890 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65  text16(),.** eve
2f8a0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c  n empty strings,
2f8b0 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f   are always zero
2f8c0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
2f8d0 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c  he return.** val
2f8e0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2f8f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f900 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  r a zero-length 
2f910 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70  BLOB is a NULL p
2f920 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  ointer..**.** <b
2f930 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54  >Warning:</b> ^T
2f940 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  he object return
2f950 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
2f960 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2f970 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  s an.** [unprote
2f980 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f990 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20  ue] object.  In 
2f9a0 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20  a multithreaded 
2f9b0 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20  environment,.** 
2f9c0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  an unprotected s
2f9d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2f9e0 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  ect may only be 
2f9f0 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68  used safely with
2fa00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2fa10 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
2fa20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
2fa30 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
2fa40 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
2fa50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
2fa60 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2fa70 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2fa80 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2fa90 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
2faa0 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
2fab0 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
2fac0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
2fad0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
2fae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2faf0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2fb00 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fb10 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65  bytes()], the be
2fb20 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68  havior is not th
2fb30 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20  readsafe..**.** 
2fb40 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
2fb50 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
2fb60 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
2fb70 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
2fb80 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
2fb90 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
2fba0 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
2fbb0 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
2fbc0 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
2fbd0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
2fbe0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2fbf0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
2fc00 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
2fc10 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
2fc20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2fc30 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
2fc40 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
2fc50 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
2fc60 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
2fc70 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
2fc80 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
2fc90 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
2fca0 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
2fcb0 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
2fcc0 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
2fcd0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
2fce0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
2fcf0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
2fd00 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
2fd10 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
2fd20 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
2fd30 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2fd40 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
2fd50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2fd60 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
2fd70 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
2fd80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2fd90 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
2fda0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42  NULL    <td>   B
2fdb0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75  LOB    <td> Resu
2fdc0 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  lt is a NULL poi
2fdd0 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
2fde0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
2fdf0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
2fe00 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
2fe10 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
2fe20 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2fe30 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2fe40 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
2fe50 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
2fe60 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2fe70 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
2fe80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
2fe90 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
2fea0 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
2feb0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
2fec0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
2fed0 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
2fee0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2fef0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2ff00 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
2ff10 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
2ff20 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
2ff30 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2ff40 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41  BLOB    <td> [CA
2ff50 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c  ST] to BLOB.** <
2ff60 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2ff70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2ff80 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2ff90 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2ffa0 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2ffb0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2ffc0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2ffd0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2ffe0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2fff0 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
30000 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
30010 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
30020 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
30030 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
30040 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30050 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
30060 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
30070 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
30080 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
30090 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64   TEXT    <td> Ad
300a0 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  d a zero termina
300b0 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a  tor if needed.**
300c0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
300d0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
300e0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
300f0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
30100 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
30110 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
30120 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
30130 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30140 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
30150 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
30160 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
30170 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
30180 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
30190 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
301a0 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
301b0 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
301c0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
301d0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
301e0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
301f0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
30200 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30210 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
30220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
30230 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
30240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30250 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
30260 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
30270 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
30280 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
30290 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
302a0 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
302b0 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
302c0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
302d0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
302e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
302f0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
30300 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30310 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
30320 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
30330 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
30340 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
30350 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
30360 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
30370 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
30380 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
30390 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
303a0 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
303b0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
303c0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
303d0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
303e0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
303f0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
30400 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
30410 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
30420 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
30430 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
30440 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
30450 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
30460 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
30470 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
30480 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
30490 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
304a0 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
304b0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
304c0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
304d0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
304e0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
304f0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
30500 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
30510 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
30520 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
30530 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
30540 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
30550 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
30560 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
30570 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
30580 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
30590 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  st policy is to 
305a0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
305b0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
305c0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
305d0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
305e0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
305f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
30600 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30620 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
30630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30640 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
30650 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30660 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
30670 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30680 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
30690 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
306a0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
306b0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
306c0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
306d0 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
306e0 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
306f0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
30700 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30710 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
30720 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30730 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
30740 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
30750 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
30760 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
30770 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
30780 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
30790 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
307a0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
307b0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
307c0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
307d0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
307e0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
307f0 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
30800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
30810 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
30820 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30830 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
30840 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
30850 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
30860 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
30870 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
30880 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30890 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
308a0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
308b0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
308c0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
308d0 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
308e0 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
308f0 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
30900 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
30910 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30920 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30930 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
30940 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
30950 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
30960 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
30970 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
30980 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
30990 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74  lly.  Do <em>not
309a0 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70  </em> pass the p
309b0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
309c0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
309d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d  3_column_blob()]
309e0 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  , [sqlite3_colum
309f0 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20  n_text()], etc. 
30a00 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  into.** [sqlite3
30a10 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _free()]..**.** 
30a20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  ^(If a memory al
30a30 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f  location error o
30a40 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65  ccurs during the
30a50 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61   evaluation of a
30a60 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72  ny.** of these r
30a70 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75  outines, a defau
30a80 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75  lt value is retu
30a90 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75  rned.  The defau
30aa0 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65  lt value.** is e
30ab0 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65  ither the intege
30ac0 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e  r 0, the floatin
30ad0 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30  g point number 0
30ae0 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a  .0, or a NULL.**
30af0 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65   pointer.  Subse
30b00 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
30b10 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
30b20 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a  )] will return.*
30b30 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  * [SQLITE_NOMEM]
30b40 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69  .)^.*/.const voi
30b50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
30b60 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
30b70 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
30b90 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
30ba0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
30bb0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
30bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
30bd0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30be0 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20  t iCol);.double 
30bf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
30c00 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
30c10 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
30c20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
30c30 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
30c40 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30c50 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
30c60 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
30c70 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
30c80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f  *, int iCol);.co
30c90 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
30ca0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
30cb0 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
30cc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
30cd0 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
30ce0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30cf0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
30d00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
30d10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30d20 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
30d30 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
30d40 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71  qlite3_value *sq
30d50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30d60 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
30d70 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a  , int iCol);../*
30d80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
30d90 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64  stroy A Prepared
30da0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
30db0 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  t.** DESTRUCTOR:
30dc0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30dd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30de0 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
30df0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
30e00 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
30e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30e20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30e30 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
30e40 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
30e50 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
30e60 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
30e70 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
30e80 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
30e90 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
30ea0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30eb0 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
30ec0 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
30ed0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
30ee0 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
30ef0 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
30f00 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
30f10 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
30f20 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
30f30 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
30f40 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
30f50 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
30f60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30f70 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
30f80 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
30f90 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
30fa0 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
30fb0 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
30fc0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30fd0 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
30fe0 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
30ff0 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
31000 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
31010 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
31020 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
31030 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
31040 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
31050 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
31060 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
31070 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
31080 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
31090 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
310a0 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
310b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
310c0 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
310d0 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
310e0 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
310f0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
31100 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
31110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31120 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
31130 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
31140 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
31150 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
31160 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
31170 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
31180 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
31190 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
311a0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
311b0 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
311c0 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
311d0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
311e0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
311f0 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
31200 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
31210 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
31220 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
31230 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
31240 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
31250 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ion..*/.int sqli
31260 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
31270 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31290 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
312a0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
312b0 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  bject.** METHOD:
312c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
312d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
312e0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
312f0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
31300 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
31310 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
31320 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
31330 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
31340 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
31350 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
31360 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
31370 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
31380 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
31390 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
313a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
313b0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
313c0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
313d0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
313e0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
313f0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
31400 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
31410 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
31420 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
31430 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
31440 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
31450 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31460 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
31470 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
31480 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
31490 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
314a0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
314b0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
314c0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
314d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
314e0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
314f0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
31500 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
31510 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
31520 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
31530 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
31540 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
31550 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
31560 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
31570 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
31580 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31590 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
315a0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
315b0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
315c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
315d0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
315e0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
315f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31600 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
31610 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
31620 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
31630 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31640 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
31650 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
31660 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
31670 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
31680 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
31690 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
316a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
316b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
316c0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
316d0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
316e0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
316f0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
31700 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
31710 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
31720 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
31730 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
31740 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31750 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31760 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
31770 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
31780 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
31790 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
317a0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
317b0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
317c0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
317d0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
317e0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
317f0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
31800 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
31810 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
31820 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
31830 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
31840 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
31850 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
31860 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
31870 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
31880 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
31890 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
318a0 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
318b0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
318c0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
318d0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
318e0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
318f0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
31900 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
31910 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
31920 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
31930 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
31940 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31950 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
31960 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
31970 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
31980 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31990 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
319a0 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
319b0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
319c0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
319d0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
319e0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
319f0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
31a00 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
31a10 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
31a20 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
31a30 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
31a40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31a50 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
31a60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
31a70 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
31a80 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
31a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
31aa0 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
31ab0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
31ac0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
31ad0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
31ae0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
31af0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
31b00 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
31b10 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
31b20 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
31b30 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
31b40 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
31b50 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
31b60 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
31b70 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
31b80 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
31b90 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
31ba0 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
31bb0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
31bc0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
31bd0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
31be0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
31bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
31c00 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
31c10 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
31c20 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
31c30 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
31c40 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
31c50 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
31c60 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
31c70 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
31c80 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
31c90 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
31ca0 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
31cb0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
31cc0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
31cd0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
31ce0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
31cf0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
31d00 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
31d10 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
31d20 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
31d30 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
31d40 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
31d50 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
31d60 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
31d70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
31d80 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
31d90 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
31da0 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
31db0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
31dc0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
31dd0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
31de0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
31df0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
31e00 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
31e10 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
31e20 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
31e30 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
31e40 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
31e50 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
31e60 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
31e70 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
31e80 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
31e90 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
31ea0 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
31eb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
31ec0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
31ed0 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
31ee0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
31ef0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
31f00 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
31f10 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
31f20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
31f30 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
31f40 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
31f50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
31f60 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
31f70 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
31f80 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
31f90 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31fa0 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
31fb0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
31fc0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
31fd0 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
31fe0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
31ff0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32000 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
32010 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
32020 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
32030 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
32040 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
32050 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
32060 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
32070 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
32080 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
32090 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
320a0 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
320b0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
320c0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
320d0 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
320e0 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
320f0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
32100 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
32110 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
32120 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
32130 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
32140 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
32150 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
32160 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
32170 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
32180 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
32190 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
321a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
321b0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
321c0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
321d0 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
321e0 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
321f0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
32200 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
32210 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
32220 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
32230 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
32240 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
32250 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
32260 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
32270 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
32280 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
32290 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
322a0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
322b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
322c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
322d0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
322e0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
322f0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
32300 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
32310 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32320 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
32330 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
32340 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
32350 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
32360 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
32370 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
32380 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
32390 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
323a0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
323b0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
323c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
323d0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
323e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
323f0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
32400 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
32410 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
32420 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
32430 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
32440 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
32450 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
32460 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
32470 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
32480 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
32490 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
324a0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
324b0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
324c0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
324d0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
324e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
324f0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
32500 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
32510 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
32520 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
32530 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
32540 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
32550 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
32560 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
32570 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
32580 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
32590 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
325a0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
325b0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
325c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
325d0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
325e0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
325f0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
32600 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
32610 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
32620 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
32630 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
32640 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
32650 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
32660 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
32670 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
32680 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
32690 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
326a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
326b0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
326c0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
326d0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
326e0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
326f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
32700 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
32710 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
32720 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
32730 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
32740 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
32750 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
32760 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
32770 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
32780 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
32790 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
327a0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
327b0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
327c0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
327d0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
327e0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
327f0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
32800 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
32810 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
32820 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
32830 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
32840 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
32850 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
32860 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
32870 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
32880 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
32890 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
328a0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
328b0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
328c0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
328d0 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
328e0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
328f0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
32900 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
32910 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
32920 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
32930 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
32940 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
32950 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
32960 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
32970 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
32980 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
32990 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
329a0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
329b0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
329c0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
329d0 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
329e0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
329f0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
32a00 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
32a10 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
32a20 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
32a30 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
32a40 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
32a50 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
32a60 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
32a70 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
32a80 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
32a90 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
32aa0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
32ab0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
32ac0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
32ad0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
32ae0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
32af0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
32b00 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
32b10 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
32b20 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
32b30 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
32b40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32b50 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
32b60 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
32b70 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
32b80 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
32b90 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
32ba0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e  s running..*/.in
32bb0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32bc0 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
32bd0 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
32be0 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
32bf0 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
32c00 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
32c10 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
32c20 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
32c30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32c40 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32c50 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32c60 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
32c70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
32c80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
32c90 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
32ca0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32cb0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
32cc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
32cd0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
32ce0 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
32cf0 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
32d00 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
32d10 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
32d20 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
32d30 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
32d40 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32d50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32d60 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
32d70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
32d80 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
32d90 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
32da0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
32db0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
32dc0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
32dd0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
32de0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
32df0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
32e00 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
32e10 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
32e20 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
32e30 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
32e40 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
32e50 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
32e60 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
32e70 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
32e80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
32e90 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
32ea0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
32eb0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
32ec0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
32ed0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
32ee0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32ef0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
32f00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
32f10 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
32f20 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
32f30 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
32f40 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
32f50 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
32f60 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
32f70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
32f80 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
32f90 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37      /* IMP: R-37
32fa0 35 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65  514-35566 */.#de
32fb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
32fc0 36 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20  6LE        2    
32fd0 2f 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d  /* IMP: R-03371-
32fe0 33 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65  37637 */.#define
32ff0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
33000 20 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49         3    /* I
33010 4d 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35  MP: R-51971-3415
33020 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
33030 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
33040 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
33050 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
33060 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
33070 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
33080 20 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63    5    /* Deprec
33090 61 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ated */.#define 
330a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
330b0 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71  GNED  8    /* sq
330c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
330d0 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a  lation only */..
330e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
330f0 46 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a  Function Flags.*
33100 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
33110 61 6e 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64  ants may be ORed
33120 20 74 6f 67 65 74 68 65 72 20 77 69 74 68 20 74   together with t
33130 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  he .** [SQLITE_U
33140 54 46 38 20 7c 20 70 72 65 66 65 72 72 65 64 20  TF8 | preferred 
33150 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61  text encoding] a
33160 73 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  s the fourth arg
33170 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
33180 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33190 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
331a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
331b0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
331c0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
331d0 6e 63 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  nction_v2()]..*/
331e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
331f0 44 45 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20  DETERMINISTIC   
33200 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41   0x800../*.** CA
33210 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74  PI3REF: Deprecat
33220 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  ed Functions.** 
33230 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a  DEPRECATED.**.**
33240 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
33250 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64   are [deprecated
33260 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20  ].  In order to 
33270 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b  maintain.** back
33280 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
33290 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63  ity with older c
332a0 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74  ode, these funct
332b0 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a  ions continue .*
332c0 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  * to be supporte
332d0 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77  d.  However, new
332e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   applications sh
332f0 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68  ould avoid.** th
33300 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66  e use of these f
33310 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e  unctions.  To en
33320 63 6f 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d  courage programm
33330 65 72 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  ers to avoid.** 
33340 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
33350 20 77 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70   we will not exp
33360 6c 61 69 6e 20 77 68 61 74 20 74 68 65 79 20 64  lain what they d
33370 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
33380 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
33390 41 54 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52  ATED.SQLITE_DEPR
333a0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
333b0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
333c0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
333d0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  xt*);.SQLITE_DEP
333e0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
333f0 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69  te3_expired(sqli
33400 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
33410 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33420 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66  t sqlite3_transf
33430 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  er_bindings(sqli
33440 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74  te3_stmt*, sqlit
33450 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
33460 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33470 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f   sqlite3_global_
33480 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53  recover(void);.S
33490 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
334a0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
334b0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
334c0 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  d);.SQLITE_DEPRE
334d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
334e0 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
334f0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
33500 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
33510 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
33520 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
33530 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
33540 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
33550 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
33560 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54  QL Values.** MET
33570 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c  HOD: sqlite3_val
33580 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  ue.**.** The C-l
33590 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
335a0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
335b0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
335c0 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
335d0 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
335e0 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
335f0 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
33600 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
33610 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
33620 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a  or aggregate.  .
33630 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
33640 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
33650 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
33660 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
33670 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
33680 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33690 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
336a0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
336b0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
336c0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
336d0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
336e0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
336f0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
33700 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
33710 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
33720 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
33730 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
33740 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
33750 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33760 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
33770 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
33780 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33790 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
337a0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
337b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
337c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
337d0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
337e0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
337f0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
33800 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
33810 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33820 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
33830 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
33840 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33850 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
33860 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
33870 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
33880 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33890 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
338a0 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
338b0 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
338c0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
338d0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
338e0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
338f0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
33900 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33910 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
33920 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74 69  that these routi
33930 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
33940 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
33950 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33960 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
33970 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
33980 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
33990 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
339a0 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
339b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
339c0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
339d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
339e0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
339f0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
33a00 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
33a10 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
33a20 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
33a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
33a40 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
33a50 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33a60 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
33a70 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
33a80 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
33a90 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
33aa0 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
33ab0 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
33ac0 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
33ad0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
33ae0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
33af0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
33b00 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
33b10 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
33b20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
33b30 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
33b40 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
33b50 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
33b60 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
33b70 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
33b80 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
33b90 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
33ba0 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
33bb0 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
33bc0 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
33bd0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
33be0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
33bf0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
33c00 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
33c10 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
33c20 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
33c30 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
33c40 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
33c50 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
33c60 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
33c70 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
33c80 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
33c90 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
33ca0 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
33cb0 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
33cc0 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
33cd0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
33ce0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
33cf0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
33d00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
33d10 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33d20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
33d30 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
33d40 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
33d50 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
33d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
33d70 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
33d80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
33d90 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
33da0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
33db0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
33dc0 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
33dd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
33de0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33df0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33e00 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
33e10 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
33e20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
33e30 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
33e40 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
33e50 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33e60 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
33e70 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
33e80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
33e90 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
33ea0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
33eb0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
33ec0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33ed0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
33ee0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
33ef0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
33f00 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
33f10 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
33f20 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
33f30 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
33f40 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
33f50 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
33f60 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
33f70 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
33f80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33f90 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
33fa0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33fb0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
33fc0 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
33fd0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
33fe0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
33ff0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
34000 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34010 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
34020 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
34030 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
34040 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34050 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
34060 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
34070 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34080 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34090 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51  EF: Obtaining SQ
340a0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
340b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
340c0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
340d0 74 65 33 5f 76 61 6c 75 65 5f 73 75 62 74 79 70  te3_value_subtyp
340e0 65 28 56 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  e(V) function re
340f0 74 75 72 6e 73 20 74 68 65 20 73 75 62 74 79 70  turns the subtyp
34100 65 20 66 6f 72 0a 2a 2a 20 61 6e 20 61 70 70 6c  e for.** an appl
34110 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34120 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  SQL function arg
34130 75 6d 65 6e 74 20 56 2e 20 20 54 68 65 20 73 75  ument V.  The su
34140 62 74 79 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  btype.** informa
34150 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
34160 20 74 6f 20 70 61 73 73 20 61 20 6c 69 6d 69 74   to pass a limit
34170 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e  ed amount of con
34180 74 65 78 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  text from.** one
34190 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
341a0 20 61 6e 6f 74 68 65 72 2e 20 20 55 73 65 20 74   another.  Use t
341b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  he [sqlite3_resu
341c0 6c 74 5f 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a  lt_subtype()].**
341d0 20 72 6f 75 74 69 6e 65 20 74 6f 20 73 65 74 20   routine to set 
341e0 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72 20  the subtype for 
341f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
34200 20 6f 66 20 61 6e 20 53 51 4c 20 66 75 6e 63 74   of an SQL funct
34210 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
34220 65 20 6d 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f  e makes no use o
34230 66 20 73 75 62 74 79 70 65 20 69 74 73 65 6c 66  f subtype itself
34240 2e 20 20 49 74 20 6d 65 72 65 6c 79 20 70 61 73  .  It merely pas
34250 73 65 73 20 74 68 65 20 73 75 62 74 79 70 65 0a  ses the subtype.
34260 2a 2a 20 66 72 6f 6d 20 74 68 65 20 72 65 73 75  ** from the resu
34270 6c 74 20 6f 66 20 6f 6e 65 20 61 70 70 6c 69 63  lt of one applic
34280 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34290 6e 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 69 6e  nction to the in
342a0 70 75 74 20 6f 66 0a 2a 2a 20 61 6e 6f 74 68 65  put of.** anothe
342b0 72 2e 0a 2a 2f 0a 75 6e 73 69 67 6e 65 64 20 69  r..*/.unsigned i
342c0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
342d0 5f 73 75 62 74 79 70 65 28 73 71 6c 69 74 65 33  _subtype(sqlite3
342e0 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  _value*);../*.**
342f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70 79 20   CAPI3REF: Copy 
34300 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56 61 6c  And Free SQL Val
34310 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
34320 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
34330 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34340 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74  value_dup(V) int
34350 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63  erface makes a c
34360 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  opy of the [sqli
34370 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
34380 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74 75 72  ject D and retur
34390 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
343a0 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54 68 65  that copy.  ^The
343b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
343c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20   returned.** is 
343d0 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  a [protected sql
343e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
343f0 63 74 20 65 76 65 6e 20 69 66 20 74 68 65 20 69  ct even if the i
34400 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a 2a 20  nput is not..** 
34410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34420 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65 72 66  ue_dup(V) interf
34430 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ace returns NULL
34440 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20 6f 72   if V is NULL or
34450 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20   if a.** memory 
34460 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73  allocation fails
34470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34480 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65 65 28  ite3_value_free(
34490 56 29 20 69 6e 74 65 72 66 61 63 65 20 66 72 65  V) interface fre
344a0 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76  es an [sqlite3_v
344b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
344c0 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
344d0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
344e0 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d 2e 20  3_value_dup()]. 
344f0 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55 4c 4c   ^If V is a NULL
34500 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6e   pointer.** then
34510 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
34520 72 65 65 28 56 29 20 69 73 20 61 20 68 61 72 6d  ree(V) is a harm
34530 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53  less no-op..*/.S
34540 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
34550 41 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  AL sqlite3_value
34560 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
34570 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74 65  dup(const sqlite
34580 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34590 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
345a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  oid sqlite3_valu
345b0 65 5f 66 72 65 65 28 73 71 6c 69 74 65 33 5f 76  e_free(sqlite3_v
345c0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
345d0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
345e0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
345f0 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45  on Context.** ME
34600 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f  THOD: sqlite3_co
34610 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
34620 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
34630 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
34640 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
34650 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
34660 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
34670 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
34680 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
34690 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
346a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
346b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
346c0 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
346d0 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
346e0 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
346f0 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
34700 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
34710 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
34720 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
34730 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
34740 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
34750 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
34760 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
34770 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
34780 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
34790 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
347a0 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
347b0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
347c0 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
347d0 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
347e0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
347f0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
34800 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
34810 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
34820 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
34830 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
34840 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
34850 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
34860 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
34870 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
34880 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
34890 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
348a0 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
348b0 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
348c0 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
348d0 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
348e0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
348f0 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
34900 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
34910 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
34920 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
34930 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
34940 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
34950 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
34960 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
34970 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
34980 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
34990 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
349a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
349b0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
349c0 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
349d0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
349e0 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66  inter .** when f
349f0 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20 4e  irst called if N
34a00 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 72   is less than or
34a10 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
34a20 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a  r if a memory.**
34a30 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20   allocate error 
34a40 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  occurs..**.** ^(
34a50 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70  The amount of sp
34a60 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  ace allocated by
34a70 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34a80 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
34a90 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64  is.** determined
34aa0 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65   by the N parame
34ab0 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63  ter on first suc
34ac0 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43  cessful call.  C
34ad0 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76  hanging the.** v
34ae0 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62  alue of N in sub
34af0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
34b00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34b10 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68  e_context() with
34b20 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61  in.** the same a
34b30 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
34b40 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20  n instance will 
34b50 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d  not resize the m
34b60 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
34b70 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20 74  ion.)^  Within t
34b80 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  he xFinal callba
34b90 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f 6d  ck, it is custom
34ba0 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d  ary to set.** N=
34bb0 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71  0 in calls to sq
34bc0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34bd0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f 20  context(C,N) so 
34be0 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e  that no .** poin
34bf0 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tless memory all
34c00 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a  ocations occur..
34c10 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75  **.** ^SQLite au
34c20 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
34c30 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
34c40 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71  ocated by .** sq
34c50 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34c60 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74  context() when t
34c70 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65  he aggregate que
34c80 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a  ry concludes..**
34c90 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61  .** The first pa
34ca0 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
34cb0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
34cc0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
34cd0 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  t | SQL function
34ce0 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69   context] that i
34cf0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
34d00 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
34d10 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20  xStep or xFinal 
34d20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
34d30 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
34d40 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a   the aggregate.*
34d50 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  * function..**.*
34d60 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
34d70 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
34d80 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
34d90 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
34da0 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  he aggregate SQL
34db0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
34dc0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
34dd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34de0 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
34df0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
34e00 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
34e10 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
34e20 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
34e30 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
34e40 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
34e50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
34e60 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
34e70 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
34e80 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
34e90 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
34ea0 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
34eb0 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
34ec0 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
34ed0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
34ee0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34ef0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
34f00 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34f10 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
34f20 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
34f30 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
34f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
34f50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
34f60 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
34f70 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
34f80 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
34f90 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
34fa0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
34fb0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34fc0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
34fd0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
34fe0 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65  user_data(sqlite
34ff0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
35000 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
35010 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
35020 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  n For Functions.
35030 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35040 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
35050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35060 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
35070 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
35080 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
35090 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
350a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
350b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
350c0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
350d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
350e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
350f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
35100 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
35110 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
35120 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
35130 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
35140 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
35150 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35160 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
35170 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
35180 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
35190 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
351a0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
351b0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
351c0 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ata.** METHOD: s
351d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a  qlite3_context.*
351e0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
351f0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
35200 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
35210 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
35220 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
35230 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
35240 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
35250 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
35260 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
35270 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
35280 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
35290 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
352a0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
352b0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
352c0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
352d0 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
352e0 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
352f0 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
35300 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
35310 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
35320 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
35330 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
35340 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
35350 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
35360 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
35370 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
35380 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
35390 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
353a0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
353b0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
353c0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
353d0 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
353e0 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
353f0 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
35400 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
35410 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
35420 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
35430 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
35440 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
35450 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
35460 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
35470 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
35480 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
35490 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
354a0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
354b0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
354c0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
354d0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
354e0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
354f0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
35500 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
35510 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35520 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
35530 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
35540 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
35550 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
35560 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
35570 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
35580 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
35590 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
355a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
355b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
355c0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
355d0 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
355e0 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
355f0 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
35600 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
35610 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
35620 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35630 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
35640 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
35650 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35660 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
35670 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
35680 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
35690 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
356a0 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
356b0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
356c0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
356d0 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
356e0 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
356f0 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
35700 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
35710 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
35720 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
35730 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
35740 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
35750 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
35760 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
35770 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
35780 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
35790 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
357a0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
357b0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
357c0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
357d0 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
357e0 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
357f0 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
35800 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
35810 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
35820 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
35830 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
35840 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
35850 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
35860 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
35870 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
35880 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
35890 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
358a0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
358b0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
358c0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
358d0 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
358e0 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
358f0 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
35900 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
35910 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
35920 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
35930 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
35940 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
35950 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
35960 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
35970 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
35980 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
35990 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
359a0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
359b0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
359c0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
359d0 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
359e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
359f0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
35a00 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
35a10 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
35a20 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
35a30 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
35a40 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
35a50 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
35a60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
35a70 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
35a80 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35a90 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
35aa0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
35ab0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
35ac0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
35ad0 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
35ae0 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
35af0 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
35b00 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
35b10 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
35b20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
35b30 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
35b40 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
35b50 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
35b60 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
35b70 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
35b80 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
35b90 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
35ba0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
35bb0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
35bc0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
35bd0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
35be0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
35bf0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
35c00 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
35c10 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
35c20 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
35c30 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
35c40 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
35c50 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35c60 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
35c70 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
35c80 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
35c90 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
35ca0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
35cb0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
35cc0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
35cd0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
35ce0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
35cf0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
35d00 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
35d10 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
35d20 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
35d30 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
35d40 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
35d50 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
35d60 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
35d70 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
35d80 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
35d90 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
35da0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
35db0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
35dc0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
35dd0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
35de0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
35df0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
35e00 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
35e10 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
35e20 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
35e30 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
35e40 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
35e50 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
35e60 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
35e70 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
35e80 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
35e90 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
35ea0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
35eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
35ec0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
35ed0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
35ee0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
35ef0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
35f00 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
35f10 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
35f20 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
35f30 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
35f40 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
35f50 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
35f60 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
35f70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
35f80 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
35f90 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
35fa0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
35fb0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
35fc0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
35fd0 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
35fe0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
35ff0 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  e3_context.**.**
36000 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36010 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
36020 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
36030 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
36040 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
36050 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36060 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
36070 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36080 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
36090 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
360a0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
360b0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
360c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
360d0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
360e0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
360f0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
36100 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
36110 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
36120 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
36130 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
36140 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
36150 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
36160 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
36170 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
36180 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
36190 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
361a0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
361b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
361c0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
361d0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
361e0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
361f0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
36200 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36210 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
36220 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
36230 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
36240 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
36250 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
36260 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
36270 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
36280 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
36290 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
362a0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
362b0 5f 7a 65 72 6f 62 6c 6f 62 28 43 2c 4e 29 20 61  _zeroblob(C,N) a
362c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  nd sqlite3_resul
362d0 74 5f 7a 65 72 6f 62 6c 6f 62 36 34 28 43 2c 4e  t_zeroblob64(C,N
362e0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
362f0 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
36300 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36310 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36320 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 42 4c  on to be.** a BL
36330 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
36340 6c 20 7a 65 72 6f 20 62 79 74 65 73 20 61 6e 64  l zero bytes and
36350 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
36360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36370 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
36380 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
36390 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
363a0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
363b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
363c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
363d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
363e0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
363f0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
36400 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
36410 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36420 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
36430 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36440 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
36450 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
36460 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
36470 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
36480 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
36490 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
364a0 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
364b0 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
364c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
364d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
364e0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
364f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
36500 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
36510 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
36520 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
36530 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
36540 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
36550 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
36560 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
36570 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
36580 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
36590 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
365a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
365b0 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
365c0 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
365d0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
365e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
365f0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
36600 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
36610 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
36620 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
36630 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
36640 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
36650 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
36660 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
36670 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
36680 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
36690 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
366a0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
366b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
366c0 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
366d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
366e0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
366f0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
36700 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
36710 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
36720 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
36730 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
36740 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
36750 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
36760 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36770 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
36780 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36790 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
367a0 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
367b0 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
367c0 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
367d0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
367e0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
367f0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
36800 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
36810 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
36820 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
36830 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
36840 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
36850 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36860 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
36870 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
36880 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
36890 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
368a0 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
368b0 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
368c0 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
368d0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
368e0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
368f0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
36900 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
36910 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36920 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
36930 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36940 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
36950 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
36960 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
36970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36980 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
36990 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
369a0 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
369b0 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
369c0 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
369d0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
369e0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
369f0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
36a00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36a10 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
36a20 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
36a30 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
36a40 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
36a50 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
36a60 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
36a70 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
36a80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36a90 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
36aa0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36ab0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
36ac0 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
36ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36ae0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
36af0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
36b00 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
36b10 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
36b20 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
36b30 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36b40 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
36b50 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
36b60 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
36b70 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36b80 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36b90 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
36ba0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
36bb0 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
36bc0 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
36bd0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
36be0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
36bf0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
36c00 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
36c10 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
36c20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36c30 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36c40 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
36c50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36c60 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
36c70 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36c80 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
36c90 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
36ca0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
36cb0 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
36cc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
36cd0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
36ce0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
36cf0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36d00 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
36d10 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
36d20 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
36d30 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
36d40 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
36d50 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
36d60 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
36d70 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
36d80 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
36d90 6c 79 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ly..** ^The sqli
36da0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 36  te3_result_text6
36db0 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
36dc0 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
36dd0 6c 75 65 20 6f 66 20 61 6e 0a 2a 2a 20 61 70 70  lue of an.** app
36de0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
36df0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
36e00 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 69 6e  a text string in
36e10 20 61 6e 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20   an encoding.** 
36e20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
36e30 20 66 69 66 74 68 20 28 61 6e 64 20 6c 61 73 74   fifth (and last
36e40 29 20 70 61 72 61 6d 65 74 65 72 2c 20 77 68 69  ) parameter, whi
36e50 63 68 20 6d 75 73 74 20 62 65 20 6f 6e 65 0a 2a  ch must be one.*
36e60 2a 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  * of [SQLITE_UTF
36e70 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
36e80 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  6], [SQLITE_UTF1
36e90 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  6BE], or [SQLITE
36ea0 5f 55 54 46 31 36 4c 45 5d 2e 0a 2a 2a 20 5e 53  _UTF16LE]..** ^S
36eb0 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20  QLite takes the 
36ec0 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d  text result from
36ed0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36ee0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64   from.** the 2nd
36ef0 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68   parameter of th
36f00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36f10 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36f20 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72  s..** ^If the 3r
36f30 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
36f40 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
36f50 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
36f60 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76  es.** is negativ
36f70 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  e, then SQLite t
36f80 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74  akes result text
36f90 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
36fa0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75  rameter.** throu
36fb0 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
36fc0 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
36fd0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
36fe0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37000 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
37010 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
37020 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79   then as many by
37030 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74  tes (not charact
37040 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74  ers) of the text
37050 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
37060 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
37070 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73  ter are taken as
37080 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37090 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63  -defined.** func
370a0 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66  tion result.  If
370b0 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   the 3rd paramet
370c0 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  er is non-negati
370d0 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d  ve, then it.** m
370e0 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
370f0 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20  offset into the 
37100 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65  string where the
37110 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
37120 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20  would.** appear 
37130 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68  if the string wh
37140 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  ere NUL terminat
37150 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
37160 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
37170 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e  .** in the strin
37180 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73  g at a byte offs
37190 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  et that is less 
371a0 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f  than the value o
371b0 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72  f the 3rd.** par
371c0 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ameter, then the
371d0 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
371e0 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65  g will contain e
371f0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64  mbedded NULs and
37200 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f   the.** result o
37210 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70  f expressions op
37220 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e  erating on strin
37230 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  gs with embedded
37240 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
37250 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  ed..** ^If the 4
37260 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
37270 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
37280 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
37290 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
372a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
372b0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
372c0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
372d0 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66   calls that.** f
372e0 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64  unction as the d
372f0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
37300 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65   text or BLOB re
37310 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73  sult when it has
37320 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69  .** finished usi
37330 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
37340 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
37350 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
37360 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37370 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ext* interfaces 
37380 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  or to.** sqlite3
37390 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
373a0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
373b0 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54  tant SQLITE_STAT
373c0 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  IC, then SQLite.
373d0 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ** assumes that 
373e0 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
373f0 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f   result is in co
37400 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64  nstant space and
37410 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70   does not.** cop
37420 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  y the content of
37430 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e   the parameter n
37440 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75  or call a destru
37450 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74  ctor on the cont
37460 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68  ent.** when it h
37470 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  as finished usin
37480 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
37490 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
374a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
374b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
374c0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
374d0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
374e0 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
374f0 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
37500 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
37510 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65  T.** then SQLite
37520 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
37530 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f   the result into
37540 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20   space obtained 
37550 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  from.** from [sq
37560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
37570 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e  before it return
37580 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
37590 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
375a0 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ue() interface s
375b0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ets the result o
375c0 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
375d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
375e0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f  ction to be a co
375f0 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 75 6e  py of the.** [un
37600 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37610 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37620 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
37630 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
37640 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
37650 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37660 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
37670 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
37680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
37690 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
376a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
376b0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
376c0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
376d0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
376e0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
376f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
37700 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
37710 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
37720 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
37730 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
37740 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
37750 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
37760 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
37770 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
37780 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
37790 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
377a0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
377b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
377c0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
377d0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
377e0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
377f0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
37800 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
37810 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
37820 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
37830 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
37840 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37850 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
37860 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
37870 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
37880 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
37890 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
378a0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
378b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
378c0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
378d0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
378e0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
378f0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
37900 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
37910 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ob64(sqlite3_con
37920 74 65 78 74 2a 2c 63 6f 6e 73 74 20 76 6f 69 64  text*,const void
37930 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  *,.             
37940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71                sq
37950 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 76 6f 69  lite3_uint64,voi
37960 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f  d(*)(void*));.vo
37970 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37980 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
37990 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
379a0 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  e);.void sqlite3
379b0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71  _result_error(sq
379c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
379d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
379e0 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
379f0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
37a00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37a10 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37a20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
37a30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
37a40 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e  obig(sqlite3_con
37a50 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
37a60 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37a70 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f  r_nomem(sqlite3_
37a80 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
37a90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37aa0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
37ab0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
37ac0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37ad0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
37ae0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
37af0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
37b00 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69  esult_int64(sqli
37b10 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
37b20 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f  lite3_int64);.vo
37b30 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37b40 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63  t_null(sqlite3_c
37b50 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73  ontext*);.void s
37b60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37b70 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
37b80 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37b90 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
37ba0 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
37bb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37bc0 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
37bd0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37be0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c  ,sqlite3_uint64,
37bf0 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
37c00 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
37c10 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
37c20 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
37c30 6e 67 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  ng);.void sqlite
37c40 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
37c50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37c60 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
37c70 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
37c80 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
37c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
37ca0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
37cb0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37cc0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
37cd0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
37ce0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37cf0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
37d00 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37d10 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
37d20 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
37d30 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37d40 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37d50 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
37d60 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
37d70 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
37d80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37d90 2a 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  *, int n);.int s
37da0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
37db0 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33  roblob64(sqlite3
37dc0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
37dd0 65 33 5f 75 69 6e 74 36 34 20 6e 29 3b 0a 0a 0a  e3_uint64 n);...
37de0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37df0 53 65 74 74 69 6e 67 20 54 68 65 20 53 75 62 74  Setting The Subt
37e00 79 70 65 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ype Of An SQL Fu
37e10 6e 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44  nction.** METHOD
37e20 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  : sqlite3_contex
37e30 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
37e40 74 65 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79  te3_result_subty
37e50 70 65 28 43 2c 54 29 20 66 75 6e 63 74 69 6f 6e  pe(C,T) function
37e60 20 63 61 75 73 65 73 20 74 68 65 20 73 75 62 74   causes the subt
37e70 79 70 65 20 6f 66 0a 2a 2a 20 74 68 65 20 72 65  ype of.** the re
37e80 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
37e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37ea0 64 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  d function with 
37eb0 63 6f 6e 74 65 78 74 20 43 0a 2a 2a 20 74 6f 20  context C.** to 
37ec0 62 65 20 54 2e 20 20 4f 6e 6c 79 20 74 68 65 20  be T.  Only the 
37ed0 6c 6f 77 65 72 20 38 20 62 69 74 73 20 6f 66 20  lower 8 bits of 
37ee0 74 68 65 20 73 75 62 74 79 70 65 20 54 20 61 72  the subtype T ar
37ef0 65 20 70 72 65 73 65 72 76 65 64 0a 2a 2a 20 69  e preserved.** i
37f00 6e 20 63 75 72 72 65 6e 74 20 76 65 72 73 69 6f  n current versio
37f10 6e 73 20 6f 66 20 53 51 4c 69 74 65 3b 20 68 69  ns of SQLite; hi
37f20 67 68 65 72 20 6f 72 64 65 72 20 62 69 74 73 20  gher order bits 
37f30 61 72 65 20 64 69 73 63 61 72 64 65 64 2e 0a 2a  are discarded..*
37f40 2a 20 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * The number of 
37f50 73 75 62 74 79 70 65 20 62 79 74 65 73 20 70 72  subtype bytes pr
37f60 65 73 65 72 76 65 64 20 62 79 20 53 51 4c 69 74  eserved by SQLit
37f70 65 20 6d 69 67 68 74 20 69 6e 63 72 65 61 73 65  e might increase
37f80 0a 2a 2a 20 69 6e 20 66 75 74 75 72 65 20 72 65  .** in future re
37f90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
37fa0 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
37fb0 33 5f 72 65 73 75 6c 74 5f 73 75 62 74 79 70 65  3_result_subtype
37fc0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37fd0 2a 2c 75 6e 73 69 67 6e 65 64 20 69 6e 74 29 3b  *,unsigned int);
37fe0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37ff0 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
38000 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
38010 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38020 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
38030 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20   functions add, 
38040 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66  remove, or modif
38050 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20  y a [collation] 
38060 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
38070 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38080 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
38090 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69  cified as the fi
380a0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
380b0 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66  .** ^The name of
380c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69   the collation i
380d0 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
380e0 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  .** for sqlite3_
380f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38100 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
38110 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
38120 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54  v2().** and a UT
38130 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e  F-16 string in n
38140 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38150 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
38160 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28  ate_collation16(
38170 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e  )..** ^Collation
38180 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70   names that comp
38190 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64  are equal accord
381a0 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ing to [sqlite3_
381b0 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a  strnicmp()] are.
381c0 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f  ** considered to
381d0 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d   be the same nam
381e0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74  e..**.** ^(The t
381f0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65  hird argument (e
38200 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65  TextRep) must be
38210 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73   one of the cons
38220 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  tants:.** <ul>.*
38230 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
38240 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  TF8],.** <li> [S
38250 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a  QLITE_UTF16LE],.
38260 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38270 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69  UTF16BE],.** <li
38280 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  > [SQLITE_UTF16]
38290 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
382a0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
382b0 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  ED]..** </ul>)^.
382c0 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70  ** ^The eTextRep
382d0 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
382e0 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e  ines the encodin
382f0 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73  g of strings pas
38300 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  sed.** to the co
38310 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
38320 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c   callback, xCall
38330 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  back..** ^The [S
38340 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64  QLITE_UTF16] and
38350 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
38360 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66  LIGNED] values f
38370 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66  or eTextRep.** f
38380 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20  orce strings to 
38390 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61  be UTF16 with na
383a0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
383b0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
383c0 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
383d0 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52  value for eTextR
383e0 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67  ep forces string
383f0 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e  s to begin.** on
38400 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64   an even byte ad
38410 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dress..**.** ^Th
38420 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
38430 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61  t, pArg, is an a
38440 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38450 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
38460 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67  passed.** throug
38470 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  h as the first a
38480 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63  rgument to the c
38490 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
384a0 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  n callback..**.*
384b0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
384c0 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b  ument, xCallback
384d0 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  , is a pointer t
384e0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
384f0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75  function..** ^Mu
38500 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67  ltiple collating
38510 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62   functions can b
38520 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  e registered usi
38530 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  ng the same name
38540 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66   but.** with dif
38550 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
38560 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53  parameters and S
38570 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77  QLite will use w
38580 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63  hichever.** func
38590 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68  tion requires th
385a0 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
385b0 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d  f data transform
385c0 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68  ation..** ^If th
385d0 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75  e xCallback argu
385e0 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65  ment is NULL the
385f0 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  n the collating 
38600 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64  function is.** d
38610 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61  eleted.  ^When a
38620 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ll collating fun
38630 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68  ctions having th
38640 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20  e same name are 
38650 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74  deleted,.** that
38660 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   collation is no
38670 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a   longer usable..
38680 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61  **.** ^The colla
38690 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
386a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
386b0 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66  d with a copy of
386c0 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70   the pArg .** ap
386d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
386e0 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20  ointer and with 
386f0 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74  two strings in t
38700 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
38710 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
38720 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
38730 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e  t.  The collatin
38740 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
38750 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74  return an.** int
38760 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67  eger that is neg
38770 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20  ative, zero, or 
38780 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74  positive.** if t
38790 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20  he first string 
387a0 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71  is less than, eq
387b0 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74  ual to, or great
387c0 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f  er than the seco
387d0 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76  nd,.** respectiv
387e0 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e  ely.  A collatin
387f0 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  g function must 
38800 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68  always return th
38810 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a  e same answer.**
388